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.

The OAuth 2.0 endpoints under /oauth2 follow standard flows (authorization code, refresh token, resource-owner password) and return JSON bodies with access_token, expires_in, and optional refresh_token or id_token values.

Token Types

Token type	How it is issued	Required headers	Typical use cases
User-scoped	Personal access tokens (POST /auth/login, POST /tokens without site_id)	Authorization, X-Nimbu-Site	Backoffice automation, multi-site tooling, testing
Site-scoped	POST /tokens with a site_id or via dashboard-generated site keys	Authorization	Storefront integrations scoped to a single site

• 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.

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

Scope	Title	Grants
openid	OpenID - Standard OpenID Claim	Access to the information it needs to log you in to a new or existing account.
profile	OpenID - Profile Claim	Access to the user profile, including the user id, email and name
email	OpenID - Email Claim	Access to the email address
full_profile	OpenID - full_profile claim	Access to the full user profile, including all fields
public	Public API Access	This includes: invoke cloud function
read_user	Read-Only Back-end User Access	Access to the back-end user profile, including the user id, email and name

Read Access

Scope	Title	Grants
read_account	Read Account Info	Access to account information
read_site	Read-Only Site Access	This includes: site settings and related settings.
read_channels	Read-Only Channel Access	All channels and entries, excluding privacy-sensitive channels
read_content	Read-Only Content Access	This includes: pages, navigation, media, copywriting, uploads, redirects and blogs.
read_coupons	Read-Only Coupon Access	This includes: customer coupons
read_customers	Read-Only Customer Access	This includes: customer accounts, groups, addresses and custom fields.
read_devices	Read-Only Device Access	This includes: device tokens
read_orders	Read-Only Order Access	Access to orders, including order items, fulfillment info and order history
read_products	Read-Only Product Access	Access to products, inventory, collections, types, vendors and custom fields
read_sensitive_channels	Read-Only Privacy-Sensitive Channel Access	Access to privacy-sensitive channels and entries.
read_themes	Read-Only Theme Access	This includes: theme source code for layouts, templates, snippets and assets.
read_cloudcode	Read-Only Cloud Code Access	All cloud code sources

Write Access

Scope	Title	Grants
write_site	Read/Write Site Access	This includes: site settings and related settings.
write_channels	Read/Write Channel Access	All channels and entries, excluding privacy-sensitive channels
write_content	Read/Write Content Access	This includes: pages, navigation, media, copywriting, uploads, redirects and blogs.
write_coupons	Read/Write Coupon Access	This includes: customer coupons
write_customers	Read/Write Customer Access	This includes: customer accounts, groups, addresses and custom fields.
write_devices	Read/Write Device Access	This includes: updating device tokens and sending push notifications
write_orders	Read/Write Order Access	Access to orders, including order items, fulfillment info and order history
write_products	Read/Write Product Access	Access to products, inventory, collections, types, vendors and custom fields
write_sensitive_channels	Read/Write Privacy-Sensitive Channel Access	Access to privacy-sensitive channels and entries.
write_themes	Read/Write Theme Access	This includes: theme source code for layouts, templates, snippets and assets.
write_cloudcode	Read/Write Cloud Code Access	All cloud code sources

Special

Scope	Title	Grants
skip_confirmation	Allow Skip Email Confirmation	Ability to skip email confirmation when creating a new customer account

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.