Authentication

Every /v1/* request needs a Bearer credential in the Authorization header: an API key or an OAuth access token. Each credential is bound to one organisation and can be revoked at any time.

API keys

Create and manage keys from Account → API Keys. Each key belongs to one organisation, inherits that organisation's plan limits, and carries the scopes you choose when you create it. Keys look like pdfs_<prefix>_<secret>; the full key is shown once, so store it securely.

Sending your key

Include the key in the Authorization header using the Bearer scheme on every request. OAuth access tokens (used by AI agents and third-party clients) go in the same header.

Never expose API keys client-side. Always call the PDFox API from your server. If a key is leaked, revoke it from the dashboard and create a new one.

Organisation

Because a key or token is bound to one organisation, orgId is optional in requests. If you do send orgId, it must match that organisation, otherwise the request fails with 403 ORG_MISMATCH.

Scopes

A request succeeds only if the credential has the scope its endpoint requires.

Scope	Endpoints
`document:create`	`POST /v1/generate`, `POST /v1/generate/jobs/{jobId}/retry`
`document:read`	`GET /v1/generate/jobs`, `GET /v1/generate/jobs/{jobId}`, `/events`, `/download`, `/file`
`usage:read`	`GET /v1/usage/quota`, `GET /v1/usage/history`
`template:read`	`GET /v1/templates`, `GET /v1/templates/{templateId}`
`template:write`	`POST /v1/templates`, `PATCH /v1/templates/{templateId}`, `POST /v1/templates/{templateId}/publish`
`asset:read`	`GET /v1/assets`, `GET /v1/assets/{assetId}/content`
`asset:write`	`POST /v1/assets`, `DELETE /v1/assets/{assetId}`

Rate limits

Each credential can make 300 requests per minute. Over the limit you get 429 with a body of { "error", "retryAfter" }, where retryAfter is an ISO 8601 timestamp of when the window resets.

Errors

Status	Meaning
`401`	Missing or malformed `Authorization` header, or the key or token is invalid, expired or revoked (`UNAUTHORIZED`)
`403`	Credential is valid but lacks the required scope (`FORBIDDEN`), `orgId` does not match the credential's organisation (`ORG_MISMATCH`), or the OAuth token's user has not verified their email (`EMAIL_NOT_VERIFIED`)
`429`	Rate limit exceeded; retry after `retryAfter`

Dashboard session cookies are not accepted on /v1/* (the only exception is GET /v1/assets/{assetId}/content). Use an API key or OAuth access token.

curl https://api.pdf-fox.com/v1/usage/quota   -H "Authorization: Bearer pdfs_<prefix>_<secret>"