# 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:

```text
https://sso.user.m7.org
```

Start with discovery instead of hard-coding endpoint URLs:

```text
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](https://m7.org/docs/api/sso.user.m7.org/browser-direct.md). 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](https://m7.org/docs/api/sso.user.m7.org/two-factor-authentication.md)
for intervals, federated-login boundaries, recovery-code reset, and unlinking.
[Email sign-in](https://m7.org/docs/api/sso.user.m7.org/email-sign-in.md) 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](https://m7.org/docs/api/sso.user.m7.org/token.md#token-exchange-rfc-8693) | 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](https://m7.org/docs/api/sso.user.m7.org/token-formats.md#requesting-client-and-receiving-application)
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](https://m7.org/docs/api/sso.user.m7.org/api-key-verification.md) 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`

```text
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:

```text
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](https://m7.org/docs/api/sso.user.m7.org/response-modes.md#web-message-popup-and-iframe)
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](https://m7.org/docs/api/sso.user.m7.org/authorization-requests.md#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:

```text
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](https://m7.org/docs/api/sso.user.m7.org/response-modes.md) 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](https://m7.org/docs/api/sso.user.m7.org/authorization-callback-outcomes.md) 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](https://m7.org/docs/api/sso.user.m7.org/response-modes.md#signed-authorization-responses-jarm)
apply before code exchange.

### 3. Exchange the code

```text
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`:

```bash
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:

```json
{
  "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:

```text
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.

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

Navigate the browser to:

```text
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:

```text
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:

```bash
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:

```bash
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:

```bash
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](https://m7.org/docs/api/sso.user.m7.org/token-formats.md) 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:

```http
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](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#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](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#issuer-values-by-token-class).
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:

```bash
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](https://m7.org/docs/api/sso.user.m7.org/userinfo.md#request) 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:

```bash
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](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#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.

```bash
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:

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

The JSON object must contain only:

```json
{
  "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:

```json
{
  "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](https://m7.org/docs/api/sso.user.m7.org/token-acknowledgement.md) for
the complete retry and state-transition contract.

## Device authorization

Start a device flow with:

```text
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:

```bash
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:

```json
{
  "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`:

```bash
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.

```bash
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:

```text
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:

```bash
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

```text
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.

```bash
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.

```bash
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`.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```text
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:

```bash
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'
```

```bash
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](https://m7.org/docs/api/sso.user.m7.org/userinfo-orgs.md), 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](https://m7.org/docs/api/sso.user.m7.org/device-authorization.md#user-approval), 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.
