Authorization and credential lifecycle

M7 SSO is the OAuth 2.0 and OpenID Connect authorization server for M7 applications. This guide describes the complete project-specific authorization contract: how clients obtain credentials, how they transmit them, which principal each credential represents, and how credentials expire, rotate, and become invalid.

The production authorization-server issuer and base URL are:

https://sso.user.m7.org

Start with discovery instead of hard-coding endpoint URLs:

GET https://sso.user.m7.org/.well-known/openid-configuration

Use HTTPS for every request. For hosted user sign-in, send the browser to /authorize; applications using this flow do not collect passwords or call M7's form-processing routes. Opted-in organization apps can use the separate browser-direct tenant protocol. It requires browser DPoP independently of ordinary client policy, keeps refresh/activation secrets at SSO, and uses its own carrier, selection and ACK contract. Confidential OAuth authentication and the hosted flow below retain their existing behavior.

Consumer two-factor checks

The consumer account can require an authenticator code for password sign-in, email sign-in, local-password Device Code approval, and remembered-account or existing-session authorization. These are independent user choices. Refresh and machine grants do not prompt for TOTP. See two-factor authentication and recovery for intervals, federated-login boundaries, recovery-code reset, and unlinking. Email sign-in supports either a magic link or a one-time code within the normal consumer authorization-code flow.

Choose an authorization flow

Integration Flow Resulting principal
Web, browser, SPA, or native application signing in a user Authorization code with PKCE Consumer user or tenant member
CLI, TV, or input-constrained device Device authorization Consumer user or tenant member
Server-to-server application acting as itself Client credentials OAuth application
Confidential service acting for a user at one connected provider Token Exchange Same user, with the requesting app recorded as actor

Authorization code with PKCE is the default for user-facing applications. Use client_credentials only for a confidential application acting as itself; it does not impersonate a user and does not issue a refresh token.

Principals and authorization boundaries

An access token represents exactly one principal. The token's audience, client, scopes, and current server-side state further limit what it can do.

Principal Subject and boundary
Consumer user sub is the M7 user ID. The token acts only as that user and within its granted audience and scopes.
Tenant member sub is the tenant member ID. The token is additionally bound to the OAuth client's tenant. Current application group-admission policy is checked at sign-in and refresh.
OAuth application sub is the public client_id. The token acts only as that application for its allowed audience and scopes.

At client-authenticated token, introspection and revocation operations, the authenticated OAuth client must match the token's requesting client_id. At a resource, client_id identifies that requester; the issuer-owned nested m7.target_client_id identifies the receiving registered app. See requester and target semantics before applying app restrictions. A tenant browser session cannot be reused for a different tenant. Tenant group membership and client policy are live authorization inputs, so applications must not assume that an earlier admission decision lasts indefinitely.

Scopes restrict disclosure and API permissions; they do not replace audience, tenant, ownership, group, or resource checks. Request only the scopes the application needs. Standard M7 OpenID Connect scopes are openid, profile, email, groups, and offline_access; client policy may allow additional application-specific scopes.

Credential inventory

Credential Format and inspection Acquisition Transmission and accepted use Lifetime and terminal behavior
client_id Public identifier; not a secret Client registration or management Form/query field where required; Basic username for client_secret_basic Valid while the client is active
Client secret High-entropy secret; do not parse Returned once when a secret-based client is registered or configured Basic password, form client_secret, or HMAC key for client_secret_jwt, according to registered method Replace if disclosed; plaintext is not retrievable later
Client assertion Compact signed JWT constructed by the client Created for one endpoint request Form fields client_assertion_type and client_assertion Short-lived, unique jti, rejected after expiry, staleness, or replay
Authorization code Opaque, confidential, single-use value Browser callback from /authorize Form field code at /token; never use as an API bearer token Approximately 10 minutes; a redemption attempt consumes it
PKCE verifier High-entropy application secret Created before /authorize Form field code_verifier at /token Retain only until the code succeeds, expires, or is abandoned
Access token Signed JWT; decoding alone does not validate it /token Use the returned token_type: Authorization: Bearer ACCESS_TOKEN for an unbound token or the endpoint's documented DPoP scheme and proof set for a token bound through cnf.jkt Short-lived; expiry, revocation, audience, client, scope, sender constraint, and server-side active state apply
Refresh token Signed JWT but opaque to the client User-authorized /token result Form field refresh_token at /token, with the returned M7 binding values Longer-lived; belongs to one client and rotates according to refresh mode
binding_chain and binding_link Opaque M7 refresh-package secrets Returned beside a refresh token Form fields when the matching refresh profile requires or supplies a binding package Rotate with the refresh package; loss prevents refresh when the binding package is required
Fingerprint 64-character hexadecimal client binding Generated and retained by an integration that uses fingerprint binding Request field on issuance and later protected or refresh requests that require it Must remain available for the bound credential or refresh lineage
ID token Signed OpenID Connect JWT Returned when openid is granted Consumed and validated by the relying party; never use as an API access token Validate signature, audience, time claims, and nonce before use
Device code Opaque secret /device_authorization Form field device_code while polling /token 10 minutes; consumed after successful pickup
User code Short human-readable lookup code; not proof by itself /device_authorization Entered only on M7's verification_uri Expires with the device authorization
ACK activation secret Opaque one-time bearer credential Pending ACK-mode refresh response JSON field activation_secret at /token/ack Retain until activation succeeds or reaches a terminal state
API key Opaque long-lived secret; do not parse or log M7 account application or API.User key management Bearer header or exact key field at /api-key/verify; resource use depends on that resource's documented policy Disabled, revoked, expired, exhausted, rotated, or deleted keys do not verify
M7 browser session M7-managed secure cookie state M7-hosted sign-in Sent by the browser only to M7 Cleared or invalidated by M7 logout/session policy

Store a refresh token, binding_chain, binding_link, fingerprint when used, and any pending ACK data as one atomic credential package. Never place access tokens, refresh tokens, ID tokens, client secrets, client assertions, binding values, fingerprints, activation secrets, or API keys in a URL or query string.

API keys are independent of OAuth access tokens and client credentials. Use the API-key verification guide for their key-only, consuming verification contract, optional audience/scope and personal-owner/organization checks, direct-client IP enforcement, and the resource checks required after a valid result.

Authorization code with PKCE

1. Create transaction values

For each sign-in attempt, create and retain:

  • state: a high-entropy, single-use CSRF correlation value;
  • code_verifier: a high-entropy PKCE secret;
  • code_challenge: base64url-encoded SHA-256 of the verifier, without padding; and
  • nonce: a high-entropy value when requesting openid.

M7 requires the literal method S256. A missing, malformed, plain, or otherwise unsupported PKCE method is rejected during authorization.

2. Navigate the browser to /authorize

GET https://sso.user.m7.org/authorize
Parameter Required Contract
client_id Yes Registered OAuth client identifier
redirect_uri Yes Exact registered HTTPS callback URI
response_type Yes code
state Yes Returned unchanged; validate before exchanging the code
code_challenge Yes 43 to 128 unreserved characters containing the PKCE challenge derived from the retained verifier
code_challenge_method Yes Must be the exact, case-sensitive value S256
scope No Space-delimited requested scopes, limited by client policy
aud No One or more exact resource audiences from the client's allowed_audiences; repeat the field for multiple values, or omit it to request the complete configured set
nonce Recommended with openid Returned in the ID token
prompt No Space-delimited, case-sensitive OIDC values none, login, consent, and select_account; M7 also supports the exclusive create extension
max_age No Non-negative maximum authentication age in seconds
login_hint No Email address or username hint

Example browser navigation, shown over several lines for readability:

https://sso.user.m7.org/authorize?
  client_id=CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback&
  response_type=code&
  scope=openid%20profile%20email&
  aud=https%3A%2F%2Fapi.example.com%2F&
  state=STATE&
  nonce=NONCE&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

M7 owns the sign-in, account-selection, signup, recovery, and other browser interaction. This example uses top-level navigation and default query delivery. Web Message provides popup and approved iframe alternatives. Do not call hosted form-processing routes as an API.

Applications require an account consent grant covering their requested scopes and audiences. First authorization, added permissions, and revoked grants show consent; an active covering grant is reused. prompt=consent requires a fresh, request-bound decision. See consent behavior for revocation and existing-token behavior. prompt=select_account forces the account chooser, including its option to use another account when no eligible account is remembered. Standard interactive prompt values may be combined; none and M7's create extension must each appear alone.

The selected audience set is case-sensitive, sealed into the authorization code, and becomes immutable for the resulting refresh lineage. A single value produces a string aud claim; several values produce a JWT audience array.

On success, M7 redirects to the exact registered URI:

https://app.example.com/oauth/callback?code=AUTHORIZATION_CODE&state=STATE

Validate state before using code. If the callback contains error, handle that error and do not attempt a code exchange.

All ten response modes use the same terminal outcome fields. Query uses a browser GET; other modes use form POST, fragment, signed JARM or a browser message. Validate the transport and, for JARM, its signature and envelope before processing the returned fields. Error callbacks include a standard OAuth error, normally a stable M7 error_reason, optional safe prose and trace information, and the original state when it was available. See Authorization callback outcomes for the complete outcome matrix, safe-return boundary, and client handling rules.

A JARM JWT is a signed authorization response, not an identity or access token. Its issuer is the canonical SSO issuer and its audience is the public OAuth client ID. It uses RS256 or RS512 independently of ID-token signing. The JARM verification rules apply before code exchange.

3. Exchange the code

POST https://sso.user.m7.org/token
Content-Type: application/x-www-form-urlencoded

Authenticate the client using its registered method. A public client using none sends client_id in the body. Example for client_secret_basic:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
  --data-urlencode 'code_verifier=CODE_VERIFIER'

redirect_uri must equal both the registered URI and the URI sealed into the authorization code. The code is consumed, the PKCE challenge is verified, and the authenticated client must match the client that received the code.

A typical user-authorized result is:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "expires_in": 900,
  "refresh_token": "REFRESH_TOKEN",
  "refresh_expires_in": 2592000,
  "binding_chain": "BINDING_CHAIN",
  "binding_link": "BINDING_LINK",
  "scope": "openid profile email",
  "id_token": "ID_TOKEN"
}

Fields and lifetimes depend on granted scopes and client policy. Treat the actual response as authoritative and persist the complete refresh package before continuing. The example is unbound. A DPoP-bound access token is returned with token_type: "DPoP" and requires the corresponding private key.

Pushed authorization requests

PAR sends authorization parameters directly to M7 before browser navigation:

POST https://sso.user.m7.org/par
Content-Type: application/x-www-form-urlencoded

Authenticate with the client's registered token-endpoint authentication method. Send the same authorization fields described above. A successful response contains a short-lived opaque request_uri:

To bind the eventual authorization code to a DPoP key, send the standard dpop_jkt authorization parameter, or send a fresh DPoP proof for exact HTU https://sso.user.m7.org/par and method POST. When both are present, they must identify the same key.

{
  "request_uri": "urn:ietf:params:oauth:request_uri:OPAQUE_VALUE",
  "expires_in": 600
}

Navigate the browser to:

https://sso.user.m7.org/authorize?client_id=CLIENT_ID&request_uri=REQUEST_URI

Do not add or override stored authorization fields in that browser request. A supplied client_id must match the pushed request. Start a new PAR transaction after expiry.

OAuth client authentication

The configured token_endpoint_auth_method controls client authentication at /token, /par, /device_authorization, and /introspect. The client must also be enabled for the requested grant type.

Method Exact request contract
none Send client_id in the form body. Intended for public clients; rejected for client_credentials, Token Exchange and introspection.
client_secret_basic Send Authorization: Basic BASE64(client_id:client_secret).
client_secret_post Send client_id and client_secret in the form body.
client_secret_jwt Send client_id, the JWT bearer assertion type, and an HMAC-signed client_assertion.
private_key_jwt Send the same assertion fields with an assertion signed by a registered private key.
tls_client_auth Present the registered CA-issued client certificate and send client_id in the form body to the operation's discovered mTLS alias.
self_signed_tls_client_auth Present the exact registered self-signed client certificate and send client_id in the form body to the operation's discovered mTLS alias.

The assertion type is:

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

For both JWT methods:

  • iss and sub must equal client_id;
  • aud must equal either the canonical authorization-server issuer https://sso.user.m7.org or the exact endpoint URL being called;
  • iat must be current and no more than 120 seconds old;
  • exp must be in the future;
  • jti must be present and unique; and
  • the registered signing algorithm must match the assertion header.

client_secret_jwt supports HS256, HS384, and HS512 according to client configuration. private_key_jwt supports RS256, RS384, RS512, and ES256; its public key comes from one registered inline jwks value or one registered HTTPS jwks_uri.

For example, an assertion sent to /par uses https://sso.user.m7.org/par as aud, while an assertion sent to /token uses https://sso.user.m7.org/token.

An mTLS-authenticated client uses the operation URL from discovery's mtls_endpoint_aliases, including the aliases for /par, /token, and /device_authorization. The browser-facing /authorize request and the authorization-server issuer remain on https://sso.user.m7.org.

Client-authentication transport examples

The authorization-code example above shows client_secret_basic. A public client configured with none uses the same exchange without --user and adds its identifier to the body:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
  --data-urlencode 'code_verifier=CODE_VERIFIER'

For client_secret_post, send the identifier and secret in the body:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'client_secret=CLIENT_SECRET' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
  --data-urlencode 'code_verifier=CODE_VERIFIER'

client_secret_jwt and private_key_jwt use the same HTTP transport; only the configured assertion signing key and algorithm differ:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=CLIENT_ASSERTION' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
  --data-urlencode 'code_verifier=CODE_VERIFIER'

Client secrets and private keys belong only in server-side secret storage. Do not embed a confidential credential in browser, SPA, native, CLI, or device application code that an end user can extract.

Access tokens

M7 access tokens are signed JWTs with current server-side session state. M7 defines separate consumer-user, tenant-member, and OAuth-application claim profiles. See Access-token formats for their decoded payload shapes. Current source emits payload typ=access for all three profiles; signed session access tokens are legacy migration inputs only.

For an unbound access token returned with token_type=Bearer, send:

Authorization: Bearer ACCESS_TOKEN

For an access token returned with token_type=DPoP, use the protected endpoint's documented Authorization: DPoP contract and send a fresh proof whose ath binds the exact access token. Do not reuse a token-endpoint proof at a protected resource. Some M7 compatibility endpoints retain a Bearer-plus-proof transport, so follow the endpoint page rather than assuming one scheme across every service.

Resource servers may decode the protected header to select the key and may inspect claims only as part of a complete validation procedure. Decoding a JWT does not validate its signature or active state. At minimum, validate:

  1. the signature using the key selected by the token header's kid;
  2. the token type and expected resource audience, plus any explicit requester (client_id) or receiving-app (m7.target_client_id) restriction;
  3. exp, nbf, and other applicable time claims;
  4. the granted scopes and principal type; and
  5. revocation or active state when the resource's risk model requires an online decision.

M7's /jwks.json response publishes all 15 asymmetric provider-signing profiles as RSA, EC, OKP, and AKP keys. Select the exact protected-header kid, require its alg and key parameters to match the configured profile, and refresh provider JWKS once when an unknown provider key appears. Personal-lineage access-token keys are absent from that set; use the fixed SSO exact-kid PEM endpoint described in signing profiles. Newly issued access tokens use iss: "https://sso.user.m7.org"; legacy access tokens and migrating ID tokens require the explicit issuer policy documented in Discovery and signing keys. Validate the exact token profile rather than treating these identifiers as interchangeable.

UserInfo bearer example

/userinfo accepts GET or POST and derives the owning OAuth client_id from the validated access token. For an unbound token:

curl --fail-with-body --silent --show-error \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  'https://sso.user.m7.org/userinfo'

The token must be active, have access-token type, represent a supported user, tenant-member, or application principal, and remain within its owning client's current policy. An optional legacy request client_id must match the token or returns insufficient_scope; an invalid, expired, revoked, or unsupported token returns invalid_token.

For a DPoP-bound token, UserInfo requires Authorization: DPoP and one fresh ath-bound proof for the exact UserInfo method and URL. M7 creates sealed, one-use internal attestations for downstream profile projections; clients do not create or transmit them. See UserInfo and scopes for the exact public request.

If a provisioned token is fingerprint-bound, send its matching fingerprint request field. Fingerprint binding is an M7 credential control; it does not replace bearer-token validation or any authorization boundary.

For fingerprint-bound UserInfo requests, use POST so the fingerprint stays out of the URL:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/userinfo' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'fingerprint=FINGERPRINT'

ID tokens

When openid is granted, /token returns an id_token signed as a JWT. It asserts the authenticated principal to the relying party identified by aud and azp; it is not an access token and must not be sent to resource APIs.

Before establishing an application session, validate the signature, key, audience, authorized party, expiry, and other time claims. If the authorization request supplied nonce, require an exact match. Use sub as the stable principal identifier. Do not use email, display name, or preferred username as a database key.

Require the protected-header algorithm to match client registration, the live ID-token discovery list and your verifier's allowlist. Select a key with the same alg and exact kid from /jwks.json, and enforce the corresponding key type and parameters. See the 15 server signing profiles for advertisement deployment and SDK compatibility status. During the current issuer migration, an ID token must carry exactly https://sso.user.m7.org or the legacy id.m7.org issuer; reject every other value. Validate each token class's issuer policy independently, even when the canonical values coincide.

Refresh packages

The default advisory binding policy allows a standard refresh request without M7 binding extensions. For a binding-required profile, send the whole stored package to /token as shown below. Optional binding policy validates a supplied package; legacy personal-lineage signing also requires its binding package.

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=REFRESH_TOKEN' \
  --data-urlencode 'binding_chain=BINDING_CHAIN' \
  --data-urlencode 'binding_link=BINDING_LINK'

The refresh token must have been issued to the authenticated client_id. When the lineage is fingerprint-bound, also send its 64-character hexadecimal fingerprint. new_fingerprint requests a replacement binding; if fingerprint is present and new_fingerprint is omitted, M7 keeps the current binding.

M7 normally uses strict_rotation when refresh_mode is omitted. The accepted M7 lifecycle modes are static, strict_rotation, grace_rotation, ack, and ack_supersede_pending. Most integrations should omit refresh_mode. Use an ACK mode only with durable, atomic storage and a tested crash-recovery procedure.

In both ACK modes, R0 remains active and the returned access and refresh credentials remain pending and unusable until ACK. With ack, another R0 refresh while R1 is pending is rejected with refresh_in_progress. With ack_supersede_pending, another valid R0 refresh issues R2, atomically revokes never-active R1, and makes only R2 eligible for ACK. ACK of the latest eligible package activates it and revokes R0.

ack_supersede_pending is a normal selectable lifecycle, not a recovery-only mode. It has the same authenticated-client, binding_chain, binding_link, conditional fingerprint, activation-secret, and conditional DPoP requirements as ack; only the pending-successor replacement policy differs.

For a normal rotated response:

  1. durably store the complete new package;
  2. atomically mark it as the active package; then
  3. discard the predecessor only after the commit succeeds.

Do not mix a new refresh token with old binding values. If the response is ambiguous or the request fails before a complete replacement is received, retain the predecessor until the selected lifecycle's documented terminal behavior proves it unusable.

ACK-mode activation

An ACK-mode refresh can return a pending replacement with an activation envelope and predecessor bundle. Persist the entire response before calling:

POST https://sso.user.m7.org/token/ack
Content-Type: application/json

The JSON object must contain only:

{
  "activation_id": "ACTIVATION_UUID",
  "activation_secret": "ACTIVATION_SECRET"
}

Do not add a bearer access token. The activation secret authorizes an unbound activation. On success M7 returns:

{
  "token_state": "active",
  "activation_id": "ACTIVATION_UUID",
  "idempotent": false
}

Only then promote the pending package and remove the predecessor. Retain all pending state after a timeout or transport failure because the outcome is ambiguous. Retry the same activation after a lost ACK response, using a fresh proof and jti when DPoP-bound; an already-completed activation returns the active result with idempotent: true.

If an ack refresh response is lost, R0 remains active but further R0 refresh attempts return refresh_in_progress until the pending proposal expires or is resolved. Under ack_supersede_pending, retained R0 can request a new pending package, atomically superseding the lost package. A stale ACK returns activation_not_current. activation_expired, activation_parent_not_current, activation_parent_invalid, and activation_not_pending are also terminal for that activation; never promote the stale package. See Token acknowledgement for the complete retry and state-transition contract.

Device authorization

Start a device flow with:

POST https://sso.user.m7.org/device_authorization
Content-Type: application/x-www-form-urlencoded

Authenticate using the client's registered method. The client must be active and enabled for the device grant. A public client may use none and send client_id in the body.

Common request fields are scope, aud, nonce, fingerprint, access_expires, refresh_expires, claims, access_claims, and refresh_claims. Requested audiences, scopes, claims, and lifetimes remain subject to client policy.

Example:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/device_authorization' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'scope=openid profile email offline_access' \
  --data-urlencode 'aud=https://api.example.com'

A successful result is valid for 10 minutes:

{
  "device_code": "DEVICE_CODE",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://sso.user.m7.org/device_login",
  "verification_uri_complete": "https://sso.user.m7.org/device_login?user_code=ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}

Keep device_code secret. Show the user verification_uri_complete and the human user_code; never ask the user to type or view device_code. The user signs in and approves only on M7's browser page.

Poll /token no more frequently than interval:

curl --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'grant_type=device_code' \
  --data-urlencode 'device_code=DEVICE_CODE'

The standard grant identifier urn:ietf:params:oauth:grant-type:device_code is also accepted. Before approval, /token returns authorization_pending. Stop polling after success, expiry, invalid_grant, or another terminal error. Successful pickup consumes the device code and returns the approved token package.

Client credentials

The client must be confidential and enabled for client_credentials. The required aud selects one allowed resource. scope, access_expires, claims, fingerprint, and a management label are optional and remain subject to policy.

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'aud=https://api.example.com' \
  --data-urlencode 'scope=resource.read' \
  --data-urlencode 'access_expires=900'

The result contains an application-principal access token and no refresh token. Obtain another token by repeating the authenticated grant when the access token expires.

Dynamic client registration

/register creates an active personal or organization-owned OAuth client for the principal represented by an access token:

POST https://sso.user.m7.org/register
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

The access token must be active and authorized for the registration operation. Omitting tenant creates a personal client. Supplying an organization UUID as tenant creates an organization-owned client only when the authenticated principal may manage that active, non-archived organization; M7 rechecks that state through creation, authentication setup, and activation. A minimal personal public-client request is:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/register' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_name": "Example App",
    "redirect_uris": ["https://app.example.com/oauth/callback"],
    "token_endpoint_auth_method": "none"
  }'

Redirect URIs are exact HTTPS values. A secret-based registration returns the plaintext client_secret in the successful registration response; store it immediately because it is not later retrievable in plaintext. A private_key_jwt registration supplies either inline jwks or one HTTPS jwks_uri, never both. An RFC 8705 registration instead selects tls_client_auth with exactly one subject-DN or SAN selector, or self_signed_tls_client_auth with exactly one inline jwks or HTTPS jwks_uri. Set tls_client_certificate_bound_access_tokens=true only when the issued access and refresh lineage must be bound to the presented certificate.

Introspection, revocation, and logout

Introspection

POST https://sso.user.m7.org/introspect
Content-Type: application/x-www-form-urlencoded

Introspection requires a confidential client authenticated with its configured method. Send token and optional token_type_hint. The authenticated client may inspect only a token issued to that client.

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/introspect' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'token=ACCESS_TOKEN' \
  --data-urlencode 'token_type_hint=access_token'

Treat active: false as unusable even when the token still decodes or its cryptographic signature remains valid. An otherwise valid token also becomes inactive when any scope or resource audience in its signed grant is removed from the client's current registration. Adding registration authority never expands an already-issued token. A token for an organization-owned client is also inactive when the organization is missing, disabled, archived, malformed, or cannot be authoritatively checked.

Ordinary list-backed token authorization

An application may bind one principal list and choose an initial membership status of active, pending, or disabled. Its list has one consumer or tenant human identity pool; machine principals are separate. SSO checks the current list association and expiry during new sign-in, issuance, and refresh. New access tokens project m7.principal with the stable list principal id, effective status (active, pending, or denied), and list. For active memberships, independent app switches can also include the current association role and JSON data; both switches default off. UserInfo and receiver ACL introspection still return the current active membership fields. The list's ordered allowed_roles and optional default_role define assignable roles; they do not enable either app token switch. A newly enrolled member uses the list default, or member when no default is set. Removing a selectable role does not change existing members' stored roles or live lookups. Pending and denied token projections omit role and data. Existing association status is preserved; expired or disabled entries project denied. The app's reject_disabled_members switch determines whether a denied member is rejected before issuance. The optional require_active_machine_membership switch requires an existing active, unexpired machine association for client credentials. Resource servers must enforce the projected status; this list does not replace organization Management membership or grant access to specific resources. Changes to a list do not rewrite already-issued access tokens. Standard /userinfo can return a live projection for a token already bearing this signed principal, bound to the same ID and application list. It cannot promote a signed pending or denied token to active.

Inbound machine principal-list ACL

POST https://sso.user.m7.org/introspect/acl is an M7-specific online access decision for a receiving application's principal list. It does not change the standard /introspect endpoint. The receiving application authenticates as a confidential client using an introspection-supported method and sends the raw inbound access token as the token form field. No caller-supplied application, organization, list, or audience selects the receiving policy. Discovery advertises this route as m7_acl_introspection_endpoint.

The token must be an active client_credentials machine token with its sub, id, and client_id identifying the same registered application. At least one value in its signed aud must exactly match an audience row in the authenticated receiving application's current allowed_audiences. For example, Post can request https://api.mailbox.service.m7.org/ when obtaining a token, and Mail must have that exact value in its stored audience rows. The receiving Client ID need not appear in the inbound token's aud. Personal admin owner proxies use the separate membership checks described below. The endpoint accepts sender-bound tokens and returns their verified cnf claim to the receiving application.

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/introspect/acl' \
  --user 'MAIL_CLIENT_ID:MAIL_CLIENT_SECRET' \
  --data-urlencode 'token=POST_ACCESS_TOKEN'

For an ordinary machine token, after Identity verifies the token, SSO rechecks the issuing client's current registration and evaluates the receiving application's ordered principal-list ACL. An app rule matches the issuing registration row UUID; an org rule matches its current parent org, not its tenant or an optional token disclosure claim. The first matching rule selects active, pending, or disabled; otherwise the application's initial membership status applies. A verified machine is added to the receiving list on its first qualifying check with that status. When a matched rule sets an expiry, SSO stores the deadline in the membership's expires column. Each later qualifying check proposes a deadline no later than the inbound token's signed expiry and extends the stored value only when the proposed deadline is later. Disabled memberships stay disabled; an expired active or pending membership can be renewed by a qualifying check. Only an effective active status yields allowed: true.

{
  "token_active": true,
  "policy_status": "active",
  "allowed": true,
  "matched_rule": 1,
  "decision_ttl_seconds": 900,
  "decision_expires_at": 1787000900,
  "membership_expires_at": "2026-08-17 21:08:20",
  "principal": {
    "id": "019AB0BC-6DD7-7CA1-B581-E30902E60311",
    "status": "active",
    "list": "019AB0BC-6DD7-7CA1-B581-E30902E60310",
    "role": "admin",
    "data": {"mailbox": "team"}
  },
  "cnf": {"jkt": "TOKEN_DPOP_KEY_THUMBPRINT"}
}

principal uses the same id, status, and list shape as the m7.principal access-token claim. It is projected for the receiving list from the current machine registration and effective ACL/association decision; it is not copied from the inbound token's own m7.principal. Its status is active, pending, or denied, with active exactly when allowed is true. Only active memberships include the current list association role and data, regardless of the receiver's token-enrichment switches. A retired selectable role can still appear here for an existing member. Callers must check allowed and status before interpreting these fields. For ordinary machines, the stable ID is checked against a read-only registry preview before enrollment. The first qualifying call creates a principal and list membership when absent. Owner proxies require both memberships to exist. Inactive tokens and applications without an active list binding have no principal response field and create no membership.

cnf is present only for a sender-bound token. The receiving application is the resource server for the inbound request. Before granting access, it must check a DPoP proof on that request against cnf.jkt, including the request method and URL, access-token hash, proof freshness, and replay. For an mTLS bound token, it must compare the certificate used on that request with cnf["x5t#S256"]. If both bindings are present, it must verify both. Reject an unsupported cnf shape. SSO cannot perform those checks because it does not receive Mail's inbound request or the certificate at Mail's trusted TLS boundary. allowed: true reports the token and ACL decision; it does not mean the sender proof has been checked.

An invalid or misaddressed token returns token_active: false and allowed: false. A valid token presented to an app without an active principal-list binding returns token_active: true, policy_status: null, and allowed: false. Policy storage failures return a server error. The decision_expires_at describes the maximum response cache window. membership_expires_at is the UTC value stored in the shared list association; it can outlive one response if another qualifying check extends the lease. Neither changes the token's signed expiry. Call on each protected request if ACL removal must take effect immediately; caching can retain an old allow result until its deadline.

Personal admin owner proxies

An access token with the signed boolean machine_owner_proxy: true remains an oauth_client token: its id, sub, and client_id identify the proxy application. The ACL response can authorize that application to act as its current registered owner user. This is a personal consumer-user proxy; organization and tenant-user proxy modes are not provided by this endpoint.

SSO MUST verify the exact raw token with Identity and recheck its current issuer-client scope and audience policy. The current sender registration MUST be active and non-archived, have admin_application: "yes", have nil tenant and org, and retain the client_credentials grant. SSO resolves the owner UID from that registration. The owner account MUST be active, non-archived, and unexpired.

The receiving list MUST be active, still belong to the authenticated receiving application's registered owner, and use the consumer identity pool. Both of these existing memberships MUST be active and unexpired:

  1. The proxy application's principal in that receiving list.
  2. The registered owner's user principal in that same receiving list.

The two principal records MUST also be active. A pending, disabled, expired, or missing membership denies access. This path never creates a principal or association and never renews a membership lease. Enrollment defaults and ordered enrollment rules do not admit a missing proxy or owner membership.

On success, principal contains the owner user's current receiving-list projection. Only the owner's membership supplies role and data. The proxy membership is an access gate; its role and data add no permissions. The additional owner_proxy object binds that effective user to the sender:

Field Meaning
owner_proxy.client_id Proxy application's public OAuth Client ID, matching the token's machine identity.
owner_proxy.principal_id Proxy application's global list-principal ID. If the token carries a signed m7.principal.id, this is the ID it must match.
owner_proxy.owner_uid Current registered owner's consumer-account UID, distinct from the global user principal ID.
owner_proxy.owner_name Owner account name, or null when unavailable. This field grants no permission.
principal.id Effective owner user's global list-principal ID.
principal.list Authenticated receiving application's list ID.

Example successful owner-proxy response, using illustrative IDs and times:

{
  "token_active": true,
  "policy_status": "active",
  "allowed": true,
  "principal": {
    "id": "22222222-2222-5222-8222-222222222222",
    "status": "active",
    "list": "33333333-3333-7333-8333-333333333333",
    "role": "member",
    "data": {"quota": 7}
  },
  "owner_proxy": {
    "client_id": "44444444-4444-7444-8444-444444444444",
    "principal_id": "11111111-1111-5111-8111-111111111111",
    "owner_uid": "55555555-5555-7555-8555-555555555555",
    "owner_name": "Alice"
  },
  "matched_rule": null,
  "decision_ttl_seconds": 300,
  "decision_expires_at": 1900000000,
  "membership_status": "active",
  "membership_expires_at": null
}

membership_status and membership_expires_at describe the owner's membership. The decision deadline is bounded by the token expiry and both membership expiries, including an earlier proxy-app expiry. cnf remains present when the verified token is sender-bound; the receiving resource still has to enforce the inbound proof.

For a valid token that fails an owner-proxy membership check, HTTP 200 carries an authorization denial with no principal or owner binding:

{
  "token_active": true,
  "policy_status": null,
  "allowed": false,
  "trace_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

trace_id is optional diagnostic metadata for correlating a failed request. SSO records which membership gate failed. Invalid token/profile or withdrawn proxy-registration authority returns token_active: false. Consumers MUST enforce the response flags and principal status; a trace ID does not grant access.

The M7 Identity SDK validates the base ACL response shape and exposes principal() plus value('owner_proxy') and value('trace_id'). It retains these fields without rewriting the token or mapping its subject to a user. Direct SDK consumers MUST interpret and validate the owner binding before using a user identity. Use it only for a verified signed boolean machine_owner_proxy: true; reject missing, malformed, or unexpected owner bindings. Require valid non-nil UUIDs for the proxy principal and owner UID, and match the actor IDs as specified above. Updated shared M7Roster performs that binding check and exposes kind=user, id=principal.id, and rid=owner_proxy.owner_uid. It still performs a fresh receiver-authenticated lookup for each machine request and carries optional denial traces. M7Roster currently refuses tokens carrying cnf until inbound sender-proof enforcement is connected.

Revocation

POST https://sso.user.m7.org/revoke
Content-Type: application/x-www-form-urlencoded

Revocation uses the client's configured authentication method: none for a public client, or client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, or self_signed_tls_client_auth for a confidential client. An mTLS client uses the discovered revocation alias. A public client sends its exact client_id and no secret. Send token and optional token_type_hint; refresh_token is accepted as a token-field alias. The authenticated client may revoke only its own token.

Public-client example:

curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/revoke' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'token=REFRESH_TOKEN' \
  --data-urlencode 'token_type_hint=refresh_token'
curl --fail-with-body --silent --show-error \
  --request POST 'https://sso.user.m7.org/revoke' \
  --user 'CLIENT_ID:CLIENT_SECRET' \
  --data-urlencode 'token=REFRESH_TOKEN' \
  --data-urlencode 'token_type_hint=refresh_token'

The endpoint returns HTTP 200 with {} for invalid, expired, already-revoked, or foreign tokens as well as successful revocation, preventing a token-status or ownership oracle. After a revocation request, discard the affected local credential package.

Browser end session

The browser endpoint is https://sso.user.m7.org/end-session and accepts GET or POST. It recognizes id_token_hint, post_logout_redirect_uri, state, client_id, logout_hint, and ui_locales.

Use id_token_hint to establish client context, but keep the ID token out of a URL by submitting a top-level form with method="post". A post_logout_redirect_uri must exactly match a registered HTTPS logout URI; without a valid ID-token hint, client_id is also required. Use a simple GET navigation only for generic logout or a client-scoped request that does not carry an ID token.

M7 validates the client and return URI before exposing a client-scoped redirect. Clear the application's own session as well; M7 cannot clear cookies on the application's domain.

DPoP status

M7 enforces each OAuth client's registered disabled, optional, or required DPoP policy at the token endpoint across authorization-code, device-code, refresh-token, and client-credentials issuance. A supplied proof is checked for its ES256 signature and public key, dpop+jwt type, exact token URL, POST method, current time, and nonempty per-request jti before grant processing. Required clients cannot issue without a valid proof. The verified key thumbprint and jti are atomically claimed in an opaque short-lived replay record, so two concurrent requests cannot spend the same proof and later reuse during the proof window is rejected.

Disabled policy blocks DPoP at /token and prevents new DPoP and fingerprint binding. An existing DPoP-bound refresh package therefore cannot refresh while that policy is active and must begin a new authorization. Optional policy binds only when the client supplies the corresponding material. Required policy mandates DPoP but does not make the separate M7 fingerprint extension mandatory. Policy changes do not promise migration of live lineages; an incompatible package may fail and require the user to sign in again.

Discovery advertises dpop_signing_alg_values_supported: ["ES256"]. Dynamic Registration accepts the standard dpop_bound_access_tokens boolean: true selects M7's required policy, while omission or false permits opportunistic DPoP. M7 currently uses freshness plus one-use jti replay protection and does not issue an authorization-server or resource-server DPoP-Nonce.

Authorization-code clients can bind the code end to end with the standard dpop_jkt authorization parameter. Direct authorization requests carry it as a query parameter. PAR accepts it in the pushed body, a fresh proof in the DPoP header, or both when their keys match. A bound code can be redeemed only with a /token proof signed by the same key.

M7 token responses derive the authorization scheme from the returned access JWT. An access token with no cnf is returned as token_type=Bearer. A token whose complete cnf object contains only a valid jkt is returned as token_type=DPoP; malformed, legacy, mixed, or ambiguous confirmation shapes fail closed instead of being mislabeled.

The proof sent to /token has no ath because it binds the issuance request, not a protected-resource use. A proof used with the resulting DPoP token must be newly signed for that resource, include ath=base64url(SHA-256(ACCESS_TOKEN)), use a unique jti, and match the token's cnf.jkt. UserInfo enforces Authorization: DPoP, exact method and URL binding, ath, key binding, and replay protection, and it can require separate proofs for its downstream live projections. Preserve the private key for the full lineage; losing it requires reauthorization.

Error handling

JSON failures use OAuth-style error and error_description fields. Branch on error, not on prose in error_description.

Error Integration action
invalid_request Correct missing, malformed, conflicting, or unsupported request data.
invalid_client Check the configured client authentication method and credential; do not retry an unchanged secret or assertion.
unauthorized_client Use only a grant or endpoint enabled for this client.
unsupported_grant_type Correct grant_type.
invalid_scope Request only exact scopes registered for the client and, during refresh, present in the authenticated lineage.
invalid_target Request only exact audiences registered for the client; refresh and grant pickup cannot replace the sealed audience set.
invalid_dpop_proof Supply a fresh valid proof for the exact token endpoint, or correct the client's registered policy.
invalid_grant Treat the code, device code, refresh token, or related package as invalid for this transaction; restart or reauthorize as appropriate.
invalid_token Reject the access token and obtain a valid credential.
insufficient_scope Do not retry as-is; correct the client, audience, scopes, tenant, ownership, or policy boundary.
authorization_pending Device flow only: continue polling at or below the supplied interval.
access_denied The principal is not admitted to the requested application or declined the request.
server_error Retry only when safe for the flow; preserve refresh or ACK recovery state across ambiguous failures.

HTTP 401 is used for invalid bearer credentials, HTTP 403 for authenticated credentials that cross a client or authorization boundary, and HTTP 400 for most malformed OAuth requests. Some transient service failures use HTTP 5xx.

Security checklist

  • Register exact HTTPS redirect and post-logout URIs.
  • Generate a fresh state and PKCE verifier for each browser flow, plus a fresh nonce whenever requesting openid.
  • Validate callback state before exchanging the authorization code.
  • Keep confidential-client authentication and code exchange off the browser.
  • Validate signed tokens before trusting claims; decoding is not validation.
  • Enforce audience, client, principal, scope, tenant, ownership, group, and resource boundaries at every protected service.
  • Store refresh packages atomically and retain predecessor data until the selected lifecycle has committed.
  • Revoke tokens and rotate client secrets after suspected disclosure.
  • Never log tokens, codes, client secrets, assertions, binding values, fingerprints, device codes, activation secrets, or M7 browser cookies.
  • Use safe placeholders in diagnostics and support material.

Consumer organization permission

The registered and consented orgs scope authorizes a separate consumer organization request, not additional standard UserInfo claims or product resource permissions. It works without openid at the org endpoint; /userinfo continues to require openid. Consumer subjects and ordinary client-credentials applications are eligible. Device authorization requires hosted device consent, and exact-endpoint DPoP, certificate and live client/token/session checks remain required. Primary email uses openid email at UserInfo; API User's account list requires its separate account.me.email.list permission and audience.