# 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](/docs/library) (searching it needs a key), download links
(`/d/...`), and a free PDF utility run on a file you hold a token for.

```bash
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](/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](/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](/docs/reference/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](#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](/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)).

## 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](/docs/reference/errors) for the full table.

## See also

- [Fill PDFs from your own data](https://getemboss.ai/use-cases/fill-pdfs-from-your-data)
- [PDF form](https://getemboss.ai/glossary/pdf-form)
- [How Emboss works](https://getemboss.ai/docs/how-emboss-works)
- [Pay per call](https://getemboss.ai/docs/pay-per-call)
- [Usage & health](https://getemboss.ai/docs/reference/usage)
- [Standard fill](https://getemboss.ai/docs/reference/sessions)
- [Fill PDF forms in Zapier workflows](https://getemboss.ai/integrations/zapier)