Authentication & scopes
Tokens belong to an organization, not to a person. They carry scopes, can be bound to specific inboxes, and can expire.
Tokens
An organization admin creates a token under Settings → Organizations → your organization → API tokens. The token is shown once. It belongs to the organization: it keeps working after the person who created it leaves, and it reaches exactly that organization — never another one its creator happens to be a member of.
Send it as a bearer token on every request:
Authorization: Bearer 12|kB3s...redacted Accept: application/json
A token is a secret with the reach of the organization. Put it in a repository secret or a vault, never in code, and give it an expiry when it lives in CI.
Scopes
A token holds one or more scopes, named resource:verb. Each endpoint requires one; a request without it is refused with 403. Grant what the script does and nothing more — a job that only reads mail does not need emails:purge.
| Scope | Grants |
|---|---|
inboxes:read | List inboxes, read one with its SMTP credentials |
inboxes:create | Create inboxes, permanent or ephemeral |
inboxes:delete | Delete an inbox |
emails:read | List, search, read and download emails and attachments; wait and expect |
emails:delete | Delete a single email |
emails:purge | Empty an inbox |
analysis:run | Deliverability and authentication analysis; the deliverability_at_least check of expect |
shares:create | Create a public share link to an email |
webhooks:read | List webhooks and their delivery history |
webhooks:write | Create, update and delete webhooks |
The original two abilities
Tokens created before the scope grammar carried read and purge. They keep working forever: read means inboxes:read plus emails:read, and purge means emails:purge. They never meant anything else, so a legacy read token cannot delete a single email or run the analysis.
Binding a token to inboxes
By default a token reaches every inbox of the organization, including ones created later. When you create it you can restrict it to a list of inboxes instead. Everything outside that list answers 404, exactly like an inbox of another organization, and the inbox listing shows only the bound ones.
A bound token cannot create inboxes: the inbox it would create is outside its own reach, which is a credential nobody can use. Use an unbound token — or one with only inboxes:create and the read scopes — for the job that creates per-run inboxes.
Expiry
A token can be given an expiry of 30 days, 90 days or a year. After that every request with it answers 401. Revoking it from the settings screen has the same effect, at once. The screen shows when each token was last used, so an unused one is easy to spot and remove.
What the status codes mean
| Status | Meaning |
|---|---|
| 401 | No token, a malformed or revoked one, an expired one, or a token whose organization was deleted |
| 403 | The token lacks the scope the endpoint requires, or is bound to inboxes and tried to create one |
| 404 | The identifier does not exist, or belongs to an inbox or organization the token does not reach |
The last row is deliberate: a token cannot be used to discover which identifiers exist. The rest of the error format is in Conventions.