Authentication
Every request to /api/v1/ and to the MCP server carries a workspace API token in the Authorization header.
Authorization: Bearer sgn_…
Generate and revoke tokens#
Open Settings, then Integrations, then the API keys tab. The API tokens section lists your tokens and has the Generate token button.
- A token is
sgn_followed by 43 characters. - The app shows the full token once, when you generate it. anymail stores only a hash of it, so nobody can show it again.
- Revoke disables a token. A revoked token returns
401. - The token list shows the name, the first characters of each token, the creation date and the date of last use. Use the last use date to find tokens that are safe to revoke.
Scope#
A token gives full access to every endpoint of its own workspace. There are no scopes and no read-only tokens. Everything the API returns belongs to that workspace. An id from another workspace behaves like an id that does not exist and returns 404.
Where the token goes#
The API accepts the token only in the Authorization header. A token in a query string is ignored, because URLs end up in access logs and browser history.
Responses#
| Situation | Status | Body |
|---|---|---|
No Authorization header, or not a Bearer scheme |
401 |
{"error":"Missing bearer token."} |
| Malformed, unknown or revoked token | 401 |
{"error":"Invalid API token."} |
A 401 response carries WWW-Authenticate: Bearer realm="anymail API". The message is the same for an unknown token and a revoked one, so a response never confirms that a token exists.
A request with a wrong token never produces a 500.
Keep tokens safe#
- Store tokens in a secret manager or an environment variable.
- Create one token per integration, so you can revoke one without touching the others.
- The
sgn_prefix lets secret scanners find a token that leaks into a repository. Revoke it at once if that happens.