Overview

Supermail is a standard OpenID Connect provider. Your application obtains a token through the authorization-code flow with PKCE, and the token is scoped to exactly the mailboxes and capabilities the user approved.

Trusted confidential applications may separately use delegated login to hand an already-authenticated application user into the Supermail portal. That creates a portal session, not an OAuth access token.

Endpoints

All endpoints are discoverable at /.well-known/openid-configuration.

The flow

  ┌─────┐                                            ┌───────────┐
  │ App │                                            │ Supermail │
  └──┬──┘                                            └─────┬─────┘
     │  1. redirect user to /oauth/authorize               │
     │  (client_id, redirect_uri, scope, state, PKCE)      │
     │ ───────────────────────────────────────────────────▶
     │                                                     │
     │           2. user logs in and consents             │
     │              (picks mailbox(es) + scopes)           │
     │                                                     │
     │  3. redirect back to redirect_uri?code=…&state=…    │
     │ ◀───────────────────────────────────────────────────
     │                                                     │
     │  4. POST /oauth/token (code + PKCE verifier)        │
     │ ───────────────────────────────────────────────────▶
     │  5. { id_token, access_token, refresh_token }       │
     │ ◀───────────────────────────────────────────────────
     │                                                     │
     │  6. call the Resource API with the access token     │
     │ ───────────────────────────────────────────────────▶

Client types

S256 PKCE is mandatory for every client. Supermail deliberately applies the same authorization-code binding to public and confidential clients.

A client_secret is shown once at registration and stored only as a hash; rotating it mints a new one while the old stays valid for a short grace window.

The app registry also divides its scope ceiling into required and recommended scopes. Both start selected during consent; users may remove recommended scopes, while required scopes are enforced end to end.

Delegated portal login

When an application already has its own users, a deployment administrator can trust its confidential client for delegated portal login. The app then uses its existing client credentials to provision an app-local subject or link an existing Supermail account, and to mint a two-minute, one-time confirmation URL.

This is independent of the OAuth flow above. Continue with the delegated-login integration guide.

What you get back

The token endpoint returns three tokens:

• an id_token with identity claims (sub, preferred_username) — the deployment has no user emails, so never an email claim;
• a short-lived access token for the Resource API;
• a rotating refresh token.

See Authentication for the access token's claims and lifetime, and Authorization for the scopes you can request.