# Teams, keys and scopes

Access has two layers: **roles** control what a person can do in the dashboard, **scopes** control
what a key can do against the API.

## Scopes

| Scope | Grants |
|---|---|
| `search:read` / `search:write` | retrieve and list searches / create, cancel, export |
| `papers:read` | paper metadata, references, citations, full text where licensed |
| `documents:read` / `documents:write` | retrieve and list / create and delete |
| `chats:read` / `chats:write` | read chats and messages / create chats, send messages |
| `extractions:read` / `extractions:write` | read rows and schemas / create schemas and runs |
| `paraphrases:write` | create paraphrases |
| `detections:write` | create AI detections |
| `topics:read` / `topics:write` | read topic searches / create them |
| `citations:read` / `citations:write` | list styles / format citations |
| `files:read` / `files:write` | download / upload |
| `usage:read` | credit balance and consumption |
| `webhooks:read` / `webhooks:write` | list endpoints / create and delete |

A call outside a key's scopes returns `403 permission_error` with `code: scope_missing`.

## Roles

| Role | Keys | Members | Billing | Usage |
|---|---|---|---|---|
| Owner | all | manage | manage | all |
| Admin | all | manage | view | all |
| Developer | create and revoke own | view | — | own keys |
| Viewer | — | view | — | view totals |

There is exactly one Owner per organization; ownership is transferable by the current Owner.

## Credits pool per organization

All keys draw from one organization balance. Two controls keep that safe:

- **Per-key monthly caps.** A key that hits its cap returns `402` while other keys keep working — the standard way to stop a batch job from starving production.
- **Auto-top-up limits.** A monthly ceiling on automatic purchases, set by the Owner.

## Recommended key layout

One key per deployment, scoped to what that deployment does: `prod-api` (read + write on the resources
it uses), `etl-worker` (extractions and files, with a monthly cap), `analytics` (`usage:read` only).
Never share a key across environments — rotation then requires a coordinated deploy.

## Related

api-keys · authentication · usage · pricing-and-credits · security-compliance