Authentication and scopes

Every request carries an API key, as Authorization: Bearer <key> or X-API-Key: <key>. Keys are created in the portal (or with POST /api-keys by a key with scope admin), shown once and stored only as a hash. Revoke a key at once if it leaks; at most 20 active keys per account.

Live and test keys

• Live keys (fkn_…) issue real invoices: archived audit-proof (GoBD), counted against your plan.
• Test keys (fkn_test_…) reach only the sandbox. They have scope invoices only.

Scopes

• invoices: issue, read, validate, check (inbound), deliver, received documents, usage, read sellers.
• admin: API keys, create and change sellers, webhooks, read sellers.

A key without the needed scope gets 403 auth.insufficient-scope. Give your production systems an invoices key and keep admin keys for setup. The last active live key and the last admin key cannot be revoked.

Errors

• 401 auth.invalid-api-key: missing, malformed or revoked key.
• 429 auth.too-many-failures: too many invalid keys from your address; wait a minute.
• 429 rate-limit.exceeded / rate-limit.concurrency: see plans and limits.

Never put a key into a browser, an app or a repository: call the API from your server.