Authentication
Workspace keys and personal keys, permissions, Project limits, IP rules and rotation.
Send your key as a bearer token on every request:
Authorization: Bearer ns_live_4eC39HqLyjWDarjtT1zdp7dc0a1b2cKeys start with ns_live_, then 38 letters and digits; the last six are a checksum, so a mistyped key is refused before anything else happens. A key that was revoked or expired answers 401 with api_key_revoked or api_key_expired.
Two kinds of keys
Workspace keys act for the Workspace. They keep working when people leave, and only the Workspace owner, admins and people with the Developer duty can create them. Creating or rolling a live one needs a passkey or an authenticator app; test keys in a sandbox only need a recent sign-in.
Personal keys act as you, with exactly your access in the app: your Projects, your accounts and your role. When you leave the Workspace, your personal keys stop working. Business owners and admins can turn personal keys off for everyone.
Either kind can only do what its permissions allow, and never more than the person who created it could do in the app.
Permissions
Choose a preset when you create a key, or pick permissions one by one.
| Permission | Allows | Read only | Publishing | Community | Full access |
|---|---|---|---|---|---|
workspace:read | Read Workspace details | Yes | Yes | ||
projects:read | Read Projects | Yes | Yes | ||
projects:write | Create and edit Projects | Yes | |||
accounts:read | Read connected accounts | Yes | Yes | Yes | Yes |
accounts:write | Connect and disconnect accounts | Yes | |||
media:read | Read media | Yes | Yes | Yes | |
media:write | Upload media | Yes | Yes | ||
posts:read | Read posts | Yes | Yes | Yes | Yes |
posts:write | Create and edit posts | Yes | Yes | ||
posts:publish | Schedule and publish posts | Yes | Yes | ||
posts:delete | Delete posts | Yes | |||
reviews:write | Approve and reject posts | Yes | |||
comments:read | Read comments | Yes | Yes | Yes | |
comments:write | Reply to comments | Yes | Yes | ||
comments:moderate | Hide and remove comments | Yes | Yes | ||
analytics:read | Read analytics | Yes | Yes | Yes | |
content:read | Read published content | Yes | Yes | Yes | Yes |
ai:use | Use AI tools (spends Tokens) | Yes | |||
usage:read | Read API usage | Yes | Yes | ||
events:read | Read events | Yes | Yes | ||
webhooks:read | Read webhooks | Yes | Yes | ||
webhooks:write | Manage webhooks | Yes |
webhooks:read and webhooks:write are available on Workspace keys only.
An endpoint that needs a permission the key lacks answers 403 insufficient_scope and names it in required_scope.
Limit a key to some Projects
A key can be limited to some Projects. Anything in other Projects answers 404, as if it did not exist.
IP allowlists
A key can accept requests only from the addresses you list (IPv4 or IPv6, single addresses or CIDR ranges). On Business, the owner can also set one rule for every key in the Workspace. Requests from other addresses answer 403 ip_not_allowed.
Rotate and revoke
Roll a key to get a new secret. The old one can keep working for 1 hour, 24 hours or 7 days while you deploy the new one, or stop at once. Revoke stops a key immediately. Keys can also be created with an expiry date.
If a key leaks, revoke it in Settings right away and create a new one.