# Authentication and scopes

Every request authenticates with a workspace API key sent as a bearer token:

```sh
curl https://optlo.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Keys have the form `optlo_live_<keyId>_<secret>`. Each key belongs to one workspace, and every request acts on that workspace.

## Creating keys

Workspace admins create keys in **Settings → API keys**. The full key is shown once, when it is created. Store it in a secret manager or environment variable, never in client-side code or a repository.

Give each integration its own key with only the scopes it needs. Separate keys can be rotated or revoked without affecting other integrations, and events record which key performed each action.

## Testing credentials

`GET /api/v1/me` works with any valid key, including a key without scopes. It returns the workspace and the key's ID, name, and scopes:

```json
{
  "workspace": { "id": "ws_…", "name": "Acme" },
  "key": { "id": "key_…", "name": "CRM sync", "scopes": ["users:read", "users:write"] }
}
```

A missing, malformed, revoked, or expired key returns `401 invalid_credentials`.

## Scopes

Each operation in the [REST reference](/docs/api-reference/rest/) lists the scope it requires. A key without that scope receives `403 permission_denied`.

| Scope                 | Grants                                                       |
| --------------------- | ------------------------------------------------------------ |
| `users:read`          | List and get users; `user.email_captured` events             |
| `users:write`         | Create and update users                                      |
| `conversations:read`  | List and get conversations; conversation events              |
| `conversations:write` | Create, close, and reopen conversations                      |
| `messages:read`       | Read customer-visible messages; `message.created` events     |
| `messages:write`      | Send messages as an operator                                 |
| `notes:read`          | Read internal notes; `note.created` events                   |
| `notes:write`         | Add internal notes                                           |
| `assistants:read`     | List and get assistants                                      |
| `assistants:write`    | Send messages as an assistant                                |
| `operators:read`      | List and get operators                                       |
| `organizations:read`  | List and get organizations                                   |
| `webhooks:manage`     | Create, list, and delete webhooks, and view delivery history |

Write scopes do not imply read scopes. An integration that creates users and then looks them up needs both `users:write` and `users:read`. Write responses return the created or updated resource without the read scope.

Some operations need more than one scope. Creating a conversation requires `conversations:write` plus `messages:write` for an operator sender, or `assistants:write` for an assistant sender. Creating a webhook requires `webhooks:manage` plus the read scope for every event type it subscribes to.

Event visibility follows read scopes. A key sees only the [events](/docs/api-reference/events/) its read scopes allow.

## Rotating and revoking keys

Rotate a key in **Settings → API keys** to replace its secret. The replacement keeps the name and scopes, and the existing key remains active for up to two hours so you can deploy the new value without downtime.

Revoke a key to stop it working immediately. Revocation cannot be undone; create a new key if the integration is needed again.

Idempotency keys are scoped to the API key that sent the request. After rotation, a retry sent with the new key starts a separate operation. See [Idempotent requests](/docs/api-reference/idempotent-requests/).
