Authentication

Updated 2026-08-23

Bearer token#

Every request carries your API key in an Authorization header:

Authorization: Bearer sk_your_api_key

curl -X POST https://api.docxtract.io/v3.1/documents \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "file=@invoice.pdf" \
  -F 'options={"model":"invoice"}'

Key format#

DocXtract keys are sk_ followed by 32 hexadecimal characters.

Warning

Note the underscore. A key with a hyphen after sk is not a DocXtract key — several other API providers use that form, and pasting one here produces a 401 invalid_api_key that looks like a server fault but is a typo. The official SDKs check the format up front and fail with a clear message instead.

Getting a key#

Generate one in the client portal under Settings. Keys are shown masked in the dashboard; use the copy control to retrieve the full value once, then store it in an environment variable — never in source control.

Alternative headers#

models also accepts:

Method	Header / parameter
Bearer (preferred)	`Authorization: Bearer sk_...`
Custom header	`X-API-Key: sk_...`
Query string	`?api_key=sk_...`

Warning

The query-string form is discouraged and only exists for legacy callers. Keys in URLs end up in server access logs, proxy logs, and browser history. Use the header.

Every other endpoint accepts Bearer only.

Checking a key without spending credits#

Two endpoints let you validate setup for free:

# is this key active?
curl https://api.docxtract.io/v3.1/authorised \
  -H "Authorization: Bearer sk_your_api_key"

# which document types may it use?
curl https://api.docxtract.io/v3.1/models \
  -H "Authorization: Bearer sk_your_api_key"

Neither deducts credits. Use them in integration setup and health checks rather than sending a throwaway document.

Authentication failures#

Code	HTTP	Meaning
`invalid_api_key`	401	Missing, malformed, unknown, or revoked key
`expired_api_key`	401	Past its `expires_at` date
`usage_limit_exceeded`	402	Key is active but its credit cap is reached

usage_limit_exceeded is not an authentication problem — the key is valid and simply out of credits. Retrying will not help; the cap needs raising.

Keys and browsers#

Danger

Never put an API key in front-end code. It is a billable credential: anyone with devtools can read it out of your page or network tab and spend your credits.

Call DocXtract from your backend and expose your own endpoint to the browser. The Node SDK deliberately ships no browser build for this reason.

Something wrong or missing on this page? Tell us.