For the complete documentation index, see llms.txt. This page is also available as Markdown.
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
402while 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
Last updated