Scopes
Every API key carries a scope list controlling which routes it may call. Six core scopes are granted by default; elevated scopes are opt-in.
Default scopes
A newly created key gets the six core scopes:
| Scope | Routes |
|---|---|
convert | POST /v1/convert, POST /v1/convert/batch, POST /v1/verify, POST /v1/anonymize |
normalize | POST /v1/normalize, POST /v1/diff |
validate | POST /v1/validate |
formats:read | GET /v1/formats, GET /v1/samples |
jobs:read | GET /v1/jobs/{id}, GET /v1/jobs/{id}/items, DELETE /v1/jobs/{id} |
enrich | POST /v1/enrich |
Opt-in scopes
These scopes are never granted by default. Select them explicitly at key creation when the key genuinely needs them; on the portal only workspace admins and owners can grant them:
| Scope | Routes | Why opt-in |
|---|---|---|
webhooks:manage | POST/GET/DELETE /v1/webhooks* | Registers URLs we deliver signed events to — account administration, not conversion |
connections:manage | POST/GET /v1/connections, DELETE /v1/connections/{id}, and the connection accounts, mappings and posts routes | Connects accounting platforms with credential-granting consequences |
transactions:post | POST /v1/connections/{id}/transactions and /transactions/dry-run; batch delivery.deliverAs: "transactions" | Posts into your books. Never a default and never implied by connections:manage |
history:read | GET /v1/history | Shows the request history of every credential in your workspace (see Request History) |
overrides:manage | GET /v1/overrides, POST /v1/overrides/validate, GET/PUT/PATCH/DELETE /v1/overrides/{name} | Changes what every conversion of your workspace emits (see Mapping Overrides) |
Reserved scopes
Two scopes exist that no key can carry:
keys:manage— key lifecycle is portal-only. No API credential can create or revoke keys, so a leaked key can never mint replacements for itself.usage:read— gatesGET /v1/usage(your month-to-date usage-vs-quota summary) andGET /v1/usage/series(hourly or daily counts). Not assignable from the portal; contact support if you need programmatic usage reads.
Behavior on a missing scope
The route responds forbidden-scope 403 — the key is valid, it just isn't allowed there. GET /v1/health, /v1/ready and /v1/version require no scope (or key) at all.
Practical guidance
Grant each key only what its system does. A statement-processing worker needs convert + maybe jobs:read; it does not need webhooks:manage. Narrow keys turn a leak into a bounded problem.