Authentication
Every API call is authenticated with an API key sent in the X-API-Key header. A key belongs to one workspace and carries the scopes that decide what it can call.
The X-API-Key header
Send your API key in the X-API-Key header on every request. The key identifies the workspace, and every resource you read or write is scoped to it.
X-API-Key: idpf_live_9f2a4c81e6b74d0fa3c5e7b921d84f60Key format
A key is idpf_live_<random>. Only a SHA-256 hash of the key is stored — the full secret is shown once, at creation. To create one, see Generate an API key.
Production and test jobs
Every job is tagged production or test, and the two are kept on separate tabs of the Jobs page — nothing else differs: credits, billing and limits are the same for both.
The tag is set per request, not by the key:
- An
environmentfield ofproductionorteston the request wins. - Otherwise the job is tagged
production.
Runs started from a pipeline's Test tab or the API Playground are tagged test.
Scopes
A key carries a list of scopes, and every endpoint requires a specific one. A request whose key lacks it gets 403. The key's scopes are the only thing that grants it access. They are chosen when the key is created and can be edited later, and nobody can grant a scope their own role does not hold.
| Scope | Grants |
|---|---|
jobs:write | Submit jobs, and retry or discard them |
jobs:read | List jobs and read their status, stages and results |
jobs:cancel | Cancel a job |
documents:read | Read documents, their lineage, events and extracted data |
pipeline:read | List and read pipelines and their versions |
pipeline:write | Create, edit and publish pipelines |
schema:read / schema:write | Read / manage extraction schemas |
webhook:read / webhook:write | Read / manage webhooks |
billing:read | Read the credit balance and billing |
api-keys:manage | Create, rotate and revoke API keys |
The full secret is returned only in the create response. Store it in your secret manager immediately. Rotating issues a new secret while the old one keeps working for an overlap window — 24 hours by default, up to 30 days — so callers migrate without downtime.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | unauthorized | No key was sent, or the key is unknown, revoked or expired. |
403 | INSUFFICIENT_SCOPE | The key is valid but lacks the scope the endpoint requires. |
403 | org_suspended | The workspace is suspended. |
403 | dunning_restricted | Invoices are unpaid; the workspace is read-only (GET still works) until they are settled. |
403 | dunning_suspended | Invoices are unpaid; all access is blocked. |
404 | varies | The resource does not exist in the key's workspace. A resource in another workspace is reported the same way. |
The two error body shapes are described in the API overview.