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; andnonce: a high-entropy value when requestingopenid.
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:
issandsubmust equalclient_id;audmust equal either the canonical authorization-server issuerhttps://sso.user.m7.orgor the exact endpoint URL being called;iatmust be current and no more than 120 seconds old;expmust be in the future;jtimust 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:
- the signature using the key selected by the token header's
kid; - the token type and expected resource audience, plus any explicit requester
(
client_id) or receiving-app (m7.target_client_id) restriction; exp,nbf, and other applicable time claims;- the granted scopes and principal type; and
- 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:
- durably store the complete new package;
- atomically mark it as the active package; then
- 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:
- The proxy application's principal in that receiving list.
- 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
stateand PKCE verifier for each browser flow, plus a freshnoncewhenever requestingopenid. - Validate callback
statebefore 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.