Authentication

The API uses API keys. Send yours as a bearer token on every request.

Send the key

Request

curl https://app.mailbench.dev/v1/workspace \
  -H "Authorization: Bearer $API_KEY"

A key starts with sbx_api_. A missing, malformed or revoked key gets 401 with the code unauthorized.

Scopes

Scope	Can
`read`	Every `GET`: list and fetch inboxes and messages, wait for mail, read checks.
`read_write`	Everything `read` can, plus creating and deleting inboxes, messages, tags and webhooks, and sending over HTTP.

A read key that tries to change something gets 403 with the code forbidden. Use read keys wherever a job only needs to look.

One key, one workspace

A key belongs to a single workspace and only ever sees that workspace's data. Another workspace's objects answer 404, never 403, so IDs cannot be probed. To work with several workspaces, use one key for each.

What keys cannot do

Keys can read team data but cannot administer it. Inviting people, managing members and keys, and billing need a signed-in dashboard session, and an API key that tries gets 403 with session_required. This is deliberate: a key that leaks from a CI log cannot mint more keys or invite anyone.

Keep keys safe

Store keys in your CI system's secrets or an environment variable. Never commit them.
Do not put a key in browser code. A page that needs to show an email can use the short-lived signed URLs in the files field of a message, which open without an Authorization header and expire after 15 minutes.
Give each pipeline its own key, so you can revoke one without breaking the others.
If a key may have leaked, revoke it in the dashboard and create a new one.
The full key is shown once, when you create it. Afterwards only its last four characters are visible.