> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate every request with an API key, and give each key only the access it needs.

## Sending your key

Send your API key as a bearer token on every request:

```bash
curl https://api.usecerium.com/v1/customers \
  -H "Authorization: Bearer $CERIUM_API_KEY"
```

Requests are only accepted over HTTPS. A request with a missing or invalid key returns `401`.

## Creating a key

Create and revoke keys in the Cerium dashboard. Choose the scopes the key needs when you create it.

## Scopes

A scope limits what a key can do. A call that needs a scope the key does not hold returns `403`.

| Scope | Allows |
| - | - |
| `customers:read` | List and get customers. |
| `customers:write` | Create, update and erase customers. |
| `conversations:read` | List and get conversations, and list their messages. |
| `conversations:write` | Start conversations, send messages, close and reopen. |

> [!TIP]
>
> Give each integration its own key with the fewest scopes it needs. A service that only displays conversations needs `conversations:read` and nothing else.

## Keeping keys safe

> [accordion] Keep keys on your servers
>
> Never ship a key in a mobile app, a browser bundle or a public repository. Anyone who holds the key can act as your company.

> [accordion] Load keys from the environment
>
> Read the key from an environment variable or a secrets manager. Do not write it into source code.

> [accordion] Rotate without downtime
>
> Create a new key, deploy it, confirm traffic has moved, then revoke the old one.

> [accordion] If a key leaks
>
> Revoke it in the dashboard straight away and create a replacement.

## Errors

| Status | Meaning |
| - | - |
| `401` | The key is missing, malformed, expired or revoked. |
| `403` | The key is valid but does not hold the scope the call needs. |
