Authentication

How to authenticate API requests with Bearer tokens.

All /v1/emails endpoints require authentication. Public endpoints (/health, /version, /openapi.json) do not.

Bearer token

Include your API key in the Authorization header:

Authorization: Bearer <your-api-key>

Example

curl -H "Authorization: Bearer 9jkLmN0pQ1rSt2uV3wX4yZ5aB6cD7eF8gH9iJ0k=" \
  "$API_URL/v1/emails?inbox=test"

How it works

1. Your request includes the plain-text token in the Authorization header
2. The API extracts the token and computes its SHA-256 hash
3. The hash is looked up in the ApiKeysTable (DynamoDB)
4. If a matching hash exists, the request proceeds
5. If no match is found, the API returns 401 UNAUTHORIZED

The plain-text token is never stored, only the hash. This means a database leak doesn't expose usable credentials.

Creating keys

API keys are managed with the provisioning CLI:

bun run provision --create --name my-key

See API Key Management for full details.

Error responses

All authentication errors return the same UNAUTHORIZED code regardless of the reason, to avoid leaking information about valid tokens.