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

# Authentication

> API keys, scopes, and how tenancy works.

Every request carries a bearer token:

```
Authorization: Bearer ck_live_…
```

## Keys

Keys are personal. Each key belongs to the member who created it — it is never shared across the team, and only its owner ever sees the token. The full token appears exactly once, at creation. Cherry stores only a hash — a lost token can't be recovered, only revoked and replaced.

Each key is scoped to one business. Everything you read or write through it is scoped to that business, attributed to the key's owner; there is no cross-business access.

**Who can create keys:** owners and admins always can. Other roles need API access enabled by an admin in Settings. Read-only roles (viewer, CPA viewer) can create `read` keys only.

## Scopes

| Scope   | Grants                                                                                |
| ------- | ------------------------------------------------------------------------------------- |
| `read`  | All `GET` endpoints and read-only MCP tools                                           |
| `write` | Everything in `read`, plus pushing bank accounts and transactions, and recategorizing |

A request with an insufficient scope returns `403` with `{"error": "forbidden", "reason": "key lacks required scope"}`.

## Failures

| Status | Meaning                                                                     |
| ------ | --------------------------------------------------------------------------- |
| `401`  | Missing, malformed, or revoked key                                          |
| `403`  | Valid key, insufficient scope — or a resource belonging to another business |
| `429`  | Rate limit reached; the response includes `Retry-After`                     |

## Revocation

Revoking a key takes effect immediately. You can revoke your own keys; owners and admins can revoke any key in the business. Revoked keys stay visible in the key list as an audit trail.