# Authentication

> Workspace keys and personal keys, permissions, Project limits, IP rules and rotation.

Send your key as a bearer token on every request:

```http
Authorization: Bearer ns_live_4eC39HqLyjWDarjtT1zdp7dc0a1b2c
```

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