Authentication

Sending Credentials

• Include Authorization: Bearer <token> on every authenticated request.
• When you authenticate with a user-scoped token, add X-Nimbu-Site: <site_id> so the API can resolve the site context.
• Site-scoped tokens already encode the site and do not require the extra header.

Create & Manage Tokens

• POST /auth/login — exchange a username and password for a user-scoped personal access token.
• GET /tokens — list the tokens visible to the caller.
• POST /tokens — mint a scoped token programmatically. Provide site_id to create a site token or omit it to stay user-scoped.
• DELETE /tokens/{token_id} — revoke a token.
• POST /auth/logout — invalidate the token currently in use.

OAuth 2.0

Register an OAuth 2 app on your site to let customers sign in to your integration. The token endpoints live on the API host:

Token responses are JSON with access_token, token_type, expires_in, and, depending on the grant, refresh_token and id_token. Confidential clients authenticate with client_id + client_secret (HTTP Basic or form fields). Public clients send only client_id.

Rules the token endpoint enforces:

• PKCE: only S256 is accepted; a challenge with any other method is rejected at authorize time. Public clients must send a code_challenge. Confidential clients may skip PKCE, but once a challenge is bound to a code, the matching code_verifier is always required.
• redirect_uri: the value sent to /oauth2/tokens must be identical to the one used at authorize time.
• Refresh tokens do not rotate. A REST refresh token can be reused until it is revoked. Only MCP grants rotate refresh tokens.
• Password grant: customers only, and only for apps with the resource-owner password grant enabled and bound to a site. The username is the customer's email.

curl -X POST "https://api.nimbu.io/oauth2/tokens" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://app.example.com/callback" \
  -d code_verifier="$CODE_VERIFIER"

Revocation. Customer tokens stop working when the customer changes their password. Backoffice user tokens stay valid until they expire, are deleted (DELETE /tokens/{token_id}, POST /auth/logout), or all of that user's tokens are revoked ("log out all sessions", or turning off two-factor authentication). Password changes and account locks do not revoke them.

To use Nimbu as a "Login with Nimbu" identity provider for other apps, see OpenID Connect. AI agents connect through the MCP server, which has its own OAuth setup (discovery, client ID metadata documents, dynamic client registration); see MCP.

Token Types

• User tokens inherit the permissions of the backoffice user. Provide X-Nimbu-Site for nearly every API call so Nimbu can load the correct site and ACLs. These tokens may see multiple sites if the account has access.
• Site tokens are already bound to one site. You can omit X-Nimbu-Site because the token resolves the site internally.
• Both token types surface granted scopes in X-OAuth-Scopes, while X-Accepted-OAuth-Scopes indicates the scopes the endpoint expected.

Customer Sessions & ACLs

Channel entry ACLs are evaluated against the current customer. Send a customer session token with Session-Token: <token> or X-Nimbu-Session-Token: <token> when a site or user token should behave like that customer. Customer OAuth tokens already resolve the customer from the bearer token.

Non-master tokens are ACL-filtered. Master tokens bypass channel and entry ACLs by default; add use_acl=true on channel entry routes when you want the same filtered view a customer would see.

See Channel Access Control for channel ACL scopes, row-level grants, and row-level denies.

Working With Scopes

• Supply the scopes array when creating or updating a token. Each scope string must match the catalogue below.
• Responses echo your active scopes in X-OAuth-Scopes. If an endpoint fails with 403, compare your scopes to the ones advertised in X-Accepted-OAuth-Scopes.
• Use separate tokens for automation with different privilege levels to adhere to least privilege.
• Tokens can be rotated without downtime by creating a new scoped token, updating clients, and then revoking the old credential.

Scope Catalogue

Identity & OpenID

See OpenID Connect for the exact claims per scope.

Read Access

Write Access

Special

Troubleshooting

• 401 Unauthorized — missing or invalid bearer token. Confirm the token is active and not revoked.
• 403 Forbidden — token is valid but lacks one or more scopes or the site ACL denies the action.
• 429 Too Many Requests — back off and retry after the time indicated in the rate limit headers.
• X-OAuth-Scopes echoes what you currently have; X-Accepted-OAuth-Scopes reveals what you still need. Compare them first when debugging access issues.