Authentication and tokens

Every API request needs a token in its Authorization header. API overview explains how to set up $NIFTY_URL and $NIFTY_TOKEN.

curl "$NIFTY_URL/api/v1/people" -H "Authorization: Bearer $NIFTY_TOKEN"

Make a token

1. Open Settings → API tokens.
2. Choose New token, or press N.
3. Give it a Name, so you can tell tokens apart.
4. Choose its Access, which is Full access or Read only (see below).
5. Choose when it Expires, which is Never or in 30, 90 or 365 days.
6. Choose Add token.
7. Copy the token, which starts with nw_. Nifty shows it only once. If you lose it, revoke it and make another.

Keep each token as safe as a password. Each token in the list shows its access, when it was last used and when it expires.

Nifty marks its answers Cache-Control: no-store, so an app's HTTP cache doesn't keep your data or the token on disk. Document files and thumbnails are the exception. An app can cache them and check them again with If-Modified-Since.

Read-only tokens

A read-only token can view all your data but can't change it. Use one for anything that only reads, such as a dashboard, a backup script or an AI app. It can use every GET and HEAD except webhooks, because their addresses are often passwords, and email forwarding, because its address lets anyone add documents. It can also use the MCP endpoint. Anything else gets 403 read_only_token.

{ "error": { "code": "read_only_token", "message": "This token is read-only. Create a token with full access in Settings → API tokens to make changes or use webhooks." } }

A token's scope in the API is full or read.

Revoke a token

1. In Settings → API tokens, choose the bin beside the token.
2. Choose Revoke token.

Apps that use the token stop working immediately. Changing your password doesn't revoke tokens, and neither does recovery.

What a token can't do

Your password, username, authenticators and API tokens are managed only in Nifty itself, so a stolen token can't lock you out, turn off two-factor authentication or make more tokens. Those endpoints answer a token with 403 session_required, and they're left out of the reference.

A token never needs a code, even when two-factor authentication is on, because the token takes the place of signing in.

When it's refused

A missing, unknown, expired or revoked token gets 401 unauthorized.

{ "error": { "code": "unauthorized", "message": "This token isn't valid." } }

When a token was sent, the response also has WWW-Authenticate: Bearer realm="Nifty", error="invalid_token". See Errors.