docs
View as Markdown

Authentication

Send your API key as a Bearer token in the Authorization header. An access token from an app you connected over OAuth works in its place. A few calls need no credential: GET /health, GET /pricing, listing the form library (searching it needs a key), download links (/d/...), and a free PDF utility run on a file you hold a token for.

curl https://api.getemboss.ai/usage \
  -H "Authorization: Bearer sk_..."

Keys start with sk_. They are scoped to your account: every key on the account sees and can change the same forms, sessions and jobs, so separate keys don't keep separate clients apart. A request for another account's resource returns 404, not 403, so existence isn't leaked across accounts.

Getting a key

Create and manage your API keys in the dashboard. You can mint a new key and rotate keys there. Keep your key out of client-side code and source control: anyone who has it can make requests on your behalf.

Key lifecycle

A key is always in one of three states, all managed from the dashboard:

  • Active: the normal state; it authenticates your requests.
  • Disabled: temporarily switched off. Requests using it return 401. This is reversible: re-enable the key in the dashboard whenever you need it again.
  • Revoked: permanently invalidated. Requests using it return 401, and it can't be brought back. Issue a new key instead.

Rotating a key is just issuing a new one and revoking the old: create the new key, move your traffic over, then revoke the previous one.

To see how much of your monthly free tier you've used, check Usage.

When a request is rejected

  • No Authorization header, or a malformed one → 401.
  • A well-formed but unknown, disabled, or revoked key → 401 (see Key lifecycle).
  • A valid key reaching a resource it doesn't own → 404.
  • No card on file and the request is past the free tier → 402. The free tier: The first 5 form creations, 5 context fills, 5 standard fills, 5 verifications, 5 reads, and 5 packages each month are free when the job is 5 pages or fewer (a context fill counts the form and its documents together); a longer job is charged and does not use a free one. Add a payment method in the dashboard to continue.
  • An app connected over OAuth whose permission doesn't cover the call (forms:read to read, forms:write to change anything) → 403.
  • Over the rate limit → 429 (see Rate limit).

Rate limit

Each API key gets 60 calls per clock hour that start work: creating a form, filling it (from documents, from your data, or by batch), preparing, verifying, reading back, quoting, suggesting a column mapping, and searching the library. Status checks, downloads and commits don't count. The count starts again at the top of each hour (UTC). A 429 carries no Retry-After header: wait for the next hour, or ask for a higher limit at contact@getemboss.ai.

See Errors & status codes for the full table.