Authentication

Every request to api.inferio.xyz carries two headers:

Header	Value	Notes
`Authorization`	`Bearer <token>`	Token from Dashboard → Settings → API keys
`X-Merchant-ID`	`<your merchant id>`	Scopes the token to your merchant. Required even though the token itself is merchant-scoped — defence-in-depth.

Tokens come in two flavours:

Prefix	Environment	Notes
`inf_dev_…`	Sandbox / dev	Use against `api-dev.inferio.xyz`. Hits the same NTA validator but documents land in the staging bucket and are purged after 7 days.
`inf_live_…`	Production	Use against `api.inferio.xyz`. Real billing, real retention per your contract.


curl https://api-dev.inferio.xyz/api/v1/ocr/requests \
  -H "Authorization: Bearer inf_dev_5e90b3..." \
  -H "X-Merchant-ID: merchant_abc123"

Generating tokens

Sign in to the dashboard
Settings → API keys
Create token — name it (e.g. production-server, staging-server), pick environment (test/live), and copy the secret immediately — we hash it server-side, so this is the only time you’ll see the plain string

Rotating tokens

Tokens are rotatable with a grace window — the old and new tokens both work for up to 24h after rotation, so you can roll updates without a window of downtime.

Dashboard → Settings → API keys → Rotate
Update your secret manager / k8s secret with the new token
Wait for the grace window or click Revoke old token when you’ve verified the new one is in use

Never embed an inf_live_* token in a browser bundle, mobile app, or anywhere a customer could exfiltrate it. The token grants full read/write access on your merchant. Server-side only.

Token scopes (coming soon)

Today’s tokens have full merchant-wide access. Per-endpoint scopes (e.g. read-only vs read+write) are on the roadmap — when they ship, the existing tokens will keep their current full-access behaviour unless you explicitly downgrade.

Drop your email on the Developers section if you want the heads-up when scopes go live.

401 vs 403 vs 200-with-error

Inferio uses three failure modes deliberately:

HTTP code	When
`401`	Token missing, malformed, or revoked
`403`	Token valid but `X-Merchant-ID` mismatch — wrong merchant
`200` + `error_code`	Application-layer business error (session expired, validation failed)

This split lets your retry logic do the right thing — 401/403 means auth is broken (don’t retry), 200-with-error means logic-level issue that may need operator attention.