Authentication

Every Emboss endpoint except GET /health requires an API key, sent as a Bearer token in the Authorization header:

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

Keys look like sk_live_…. They are scoped to a single owner — a key can only read and mutate the forms and sessions created with that same key. A request for another owner'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.
• You're over the monthly free tier with no card on file → 402. Add a payment method in the dashboard to continue.
• You've exceeded the request rate limit → 429. Slow down and retry.

See Errors & status codes for the full table.