# Authentication

> Authenticate requests with secret API keys via Bearer tokens.

Source: https://tickos.dev/docs/authentication

TickOS uses API keys to authenticate requests. Keys start with sk_ and belong to a single workspace: every request is scoped to the workspace that owns the key. Send your key in the Authorization header as a Bearer token.

```http
Authorization: Bearer sk_your_api_key
```

The Bearer prefix is recommended. For backwards compatibility the API also accepts the bare key (Authorization: sk_your_api_key).

## Permission levels

Each key has one of three permission levels. Higher levels include the lower ones (admin > write > read). Each endpoint page states the permission it requires.

| Permission | Allows |
|---|---|
| read | Read endpoints (list, retrieve and stats), plus a few non-destructive actions such as POST /v1/connections/{id}/verify-outbound (re-checking a domain verification). |
| write | Everything in read, plus creating, updating and most deletes (tags, contact groups and their members, automations, changelog entries, draft messages, scheduled emails, team members...). |
| admin | Everything in write, plus deleting tickets, customers, inboxes, connections and campaigns, and managing API keys (/v1/keys). |

## Authentication errors

| Status | When |
|---|---|
| 401 | The Authorization header is missing, the key does not start with sk_, or the key is invalid or revoked. |
| 403 | The key is valid but its permission level is lower than the one the endpoint requires. |

403 response:

```json
{
  "error": "Insufficient permissions",
  "message": "This endpoint requires \"admin\" permission, but your key has \"write\" permission"
}
```

> **Keep secrets safe:** Never commit secret keys to source control or expose them in client-side code. If a key leaks, revoke it immediately from Settings > Developers and create a new one.