Authentication
How your application authenticates to the API — the Supermail access token and how to obtain and present it.
The Resource API is authenticated with a Supermail access token: a short-lived, signed token your application obtains through the OAuth 2.1 authorization flow and presents on every call.
This is separate from delegated portal login: a delegated login URL creates a browser session for the user, but never gives the application a Resource API token.
Obtaining a token
- Register your application to get a
client_id(and, for confidential clients, aclient_secret). - Run the authorization-code + PKCE flow so the user consents to the scopes your app requests.
- Exchange the code for an
id_token, an access token, and a rotating refresh token.
Presenting the token
Send the access token as a bearer credential on every Resource API request:
Authorization: Bearer <access_token>Bearer tokens are accepted only in the Authorization header. Supermail does
not accept them in URI query parameters, where credentials can leak through
browser history, access logs, and referrer metadata.
The access token is a signed JWT with these claims:
| Claim | Meaning |
|---|---|
iss | The issuer — your deployment's base URL |
sub | The authorizing user's id |
client_id | Your application |
grant_id | The grant this token acts under |
scope | The scopes granted at issuance |
- Access tokens are short-lived (~10 minutes). When one expires, use the refresh token at the token endpoint to get a new one.
- The token's signing key is published at the JWKS endpoint so you can verify it offline.
The scope claim reflects the grant at issuance time. It is not the
authority the API applies: every call re-resolves the live grant named by
grant_id, so a revoked or narrowed grant is enforced immediately — before
the access token expires. Never treat the scope claim as durable
permission. See Authorization.
Refresh tokens
The token endpoint returns a rotating refresh token: each refresh yields a new refresh token and invalidates the previous one. Reusing an old refresh token is treated as a compromise and kills the whole token family — store only the latest one. To proactively invalidate a token, use the revocation endpoint.
Content type
JSON requests to the RPC endpoint must be sent with
Content-Type: application/json. Raw content reads carry bearer authorization
without a JSON envelope; see Transports.