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

# Authentication & API keys

> Authenticate with cx-api-key, scopes, and least-privilege keys for agents.

All Public API requests require an API key in the `cx-api-key` HTTP header:

```
cx-api-key: your-api-key-here
```

Requests without a valid key receive `401` with code `API_KEY_REQUIRED` or `INVALID_API_KEY`.

## Create and manage keys

Create keys in [Settings → API](https://armin.cx/app/_/settings/api). Each key is scoped to one organization — you cannot access another workspace's data with the same key.

| Action     | Where                                           |
| ---------- | ----------------------------------------------- |
| Create key | Settings → API → **Create API key**             |
| Rotate     | Create a new key, deploy it, delete the old key |
| Revoke     | Settings → API → delete the key                 |

<Tip>
  Name keys by purpose (`prod-warehouse-sync`, `staging-ai-agent`) so you know which integration to update during rotation.
</Tip>

## Scopes

Scopes limit what a key can do. New keys default to **`tickets:read`** only.

| Scope            | Grants (v1)                                                                          |
| ---------------- | ------------------------------------------------------------------------------------ |
| `tickets:read`   | `GET /public/v1/tickets`, `/tickets/:n`, `/tickets/:n/messages`, `/views`, `/health` |
| `tickets:write`  | Legacy `POST /public/tickets` (create ticket)                                        |
| `tickets:export` | Legacy `POST /public/tickets/export`                                                 |
| `analytics:read` | Legacy statistics and agent metrics endpoints                                        |

A key missing the required scope receives `403` with code `FORBIDDEN_SCOPE`.

### Least privilege for AI agents

For read-only agent tools that list tickets, read threads, and summarize conversations:

1. Create a key with **only** `tickets:read`.
2. Do not grant `tickets:write` or `tickets:export` unless the agent must call legacy write/export endpoints.
3. Link the key to a specific agent when you want view access to match that agent's inbox permissions (see below).

### Legacy keys without scopes

Keys created before scopes shipped may have an empty `scopes` column. Those keys retain **full access** during the migration window. Re-create keys with explicit scopes when you rotate.

## Agent-linked keys and view access

When an API key is linked to a support agent:

* **`GET /views`** returns only views that agent can see in the inbox.
* **`GET /tickets?view_id=...`** returns `404 VIEW_NOT_FOUND` if the view is not accessible to that agent.

Service keys with **no linked agent** see all organization views.

<Warning>
  If your agent integration cannot find a view that exists in the UI, check whether the API key is agent-linked and whether that agent has access to the view's sharing rules.
</Warning>

## Security practices

* Never expose API keys in client-side code, public repos, or browser extensions.
* Rotate keys immediately if one is leaked.
* Use separate keys per environment (staging vs production).
* Prefer scoped keys over legacy full-access keys.

## Related

* [Getting started](/api/getting-started) — first request walkthrough
* [Errors](/api/errors) — `FORBIDDEN_SCOPE` and other auth error codes