Copy page

Getting started

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
Authorization: Bearer <token>

Personal Access Tokens (PAT)

A PAT authenticates as you — it carries your own team membership and permissions. Create one from your Nifty account settings; the token is shown once at creation time and looks like:

Code
nft_user_<prefix>_<secret>

Use it exactly like any bearer token:

Code
curl https://openapi.niftypm.com/api/v1.0/projects \
  -H "Authorization: Bearer nft_user_<prefix>_<secret>"

Scope requirement for the legacy REST API

This applies to both credential types — PAT and OAuth 2.1 alike — and to the whole legacy REST surface, both /api/v1.0/* and /api/v2.0/*. The check runs on every route either version protects; it does not inspect the version prefix, so a token refused on a v1.0 route is refused on its v2.0 twin in exactly the same way.

A token passes when either of these is true:

• it carries the Full access (admin) tier, which passes everywhere; or
• 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.

For example, GET /api/v1.0/tasks is satisfied by tasks:read, and equally by the broader read macro or by tasks:write (write implies read). The same token also satisfies GET /api/v2.0/tasks.

Resources outside Nifty's scope catalog still require Full access. The resource-and-action rule currently covers tasks, projects, docs, labels and members. Every other segment — and a handful of individual routes within the covered ones — falls back to demanding admin, and a narrower token is rejected there with 403 Forbidden. This list grows over time; treat Full access as the fallback whenever a narrower token gets a 403.

OAuth 2.1 (third-party apps)

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.

OAuth 2.1 tokens are always fine-grained — the authorization server never issues the admin tier — so they reach the legacy REST API through the resource-and-action rule above. An OAuth token granted tasks:read can call GET /api/v1.0/tasks and GET /api/v2.0/tasks. It is refused on any segment the catalog does not cover, since those still require Full access.

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.