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`
`normalize`	`POST /v1/normalize`
`validate`	`POST /v1/validate`
`formats:read`	`GET /v1/formats`
`jobs:read`	`GET /v1/jobs/{id}`, `DELETE /v1/jobs/{id}`
`enrich`	`POST /v1/enrich`

Opt-in scopes

Two scopes are never granted by default — select them explicitly at key creation when the key genuinely needs 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}`	Connects accounting platforms with credential-granting consequences

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 — gates GET /v1/usage (your month-to-date usage-vs-quota summary). 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.

Was this page helpful?