Authentication
The Nifty API accepts two kinds of bearer credentials: a Personal Access Token (PAT) for a single member's own access, and an OAuth 2.1 token for a third-party app acting on behalf of a team.
Every request carries the credential the same way, regardless of which kind it is:
Code
Personal Access Tokens (PAT)
A PAT authenticates as you — it carries your own team membership and permissions. Create one under Settings → API Tokens (see Getting started). The token is shown once and has four parts:
Code
A truncated paste fails with the same 401
{"type":"unauthorized","code":"unauthorized"} as a missing or revoked token —
the shape does not tell the two apart, so verify the token round-tripped intact
before assuming it was revoked.
Use it exactly like any bearer token:
Code
Legacy v1.0:
Code
Scope requirement for the legacy REST API
This applies to both credential types — personal access tokens and OAuth 2.1 tokens alike.
A token passes when it carries a scope covering the resource and action the
request implies: the resource from the path segment after the version prefix,
the action from the HTTP method. GET /api/v1.0/tasks is satisfied by
tasks:read, and equally by the broader read macro or by tasks:write
(write implies read).
Fine-grained scopes cover tasks, projects, docs, labels and members.
Other legacy segments, and some individual routes inside the covered ones,
answer 403 to a fine-grained token. The token is still valid — a refresh will
not change the outcome. Use the v3 API for those resources.
OAuth 2.1 (third-party apps)
New integrations use the OAuth 2.1 server at https://api.niftypm.com — see
Authorization.
If you're building an integration rather than scripting your own account,
register a Nifty app and take a team through the OAuth 2.1 authorization
flow. The resulting access token is issued in the same shape as a PAT
(nft_oauth_<...>) and is presented the same way — Authorization: Bearer nft_oauth_<...>.
Authorization (OAuth 2.1) documents the whole flow: the discovery document, authorization-code exchange with PKCE, refresh tokens and their lifetimes, the scope model, and redirect URI rules.
An OAuth 2.1 token granted tasks:read can call GET /api/v1.0/tasks. It is
refused on the segments listed above.
Errors
Three error shapes reach you from this host, depending on which surface answered:
| Surface | Shape |
|---|---|
v3 (/api/v3/*) | RFC 7807 problem details — branch on code, follow docsUrl |
Legacy (/api/v1.0/*) | { "message": "…", "code": 401 } |
OAuth (/oauth/*) | RFC 6749 { "error": "…", "error_description": "…" } |
Every v3 code is listed, with its HTTP status and what to do about it, on
Errors.
Trying it out here
Use the API tokens page (top navigation) to save a token in your browser and drive the "Try it" panel on any endpoint below — nothing is sent anywhere except the request you trigger.