# M7 SSO API reference

<!-- m7-identity-discovery:begin -->
## Connect to M7 Identity

Issuer: <https://sso.user.m7.org>

Discovery JSON: <https://sso.user.m7.org/.well-known/openid-configuration>

- [Discovery and signing keys](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md)
- [Integration quickstart](https://m7.org/docs/api/sso.user.m7.org/quickstart.md)
- [Provider profile](https://m7.org/docs/api/sso.user.m7.org/provider-profile.md)
- [M7 Identity SDK and current downloads](https://m7.org/docs/sdk/m7-identity/)

Live discovery supplies endpoint locations and advertised capabilities. Use the
provider profile for the integration contract and current testing status.
<!-- m7-identity-discovery:end -->

M7 SSO is the production OAuth 2.0 and OpenID Connect authorization service
for M7 applications. It signs users in, issues and refreshes credentials,
supports machine grants and delegated user access between connected apps,
and returns identity claims to registered
clients.

The production API base URL and authorization-server issuer returned by
discovery are:

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

M7 access tokens and migrating ID tokens use token-class-specific issuer
rules. Before configuring JWT validation, read
[Issuer values by token class](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#issuer-values-by-token-class).

Start with OpenID Connect discovery rather than hard-coding endpoint URLs:

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

Use the [M7 account application](https://user.m7.org/) to manage accounts,
organizations, linked identities, OAuth applications, and API keys. The
[M7 User API](https://m7.org/docs/api/api.user.m7.org/) provides the related
account and application-management API after sign-in.

## Choose an integration

| Need | Use |
| --- | --- |
| Evaluate the complete supported protocol contract | [M7 Provider Profile](https://m7.org/docs/api/sso.user.m7.org/provider-profile.md) |
| Scan the current compatibility surface | [Provider capability card](https://m7.org/docs/api/sso.user.m7.org/provider-capabilities.md) |
| Browser, server-rendered web app, SPA, or native app | [Authorization code with PKCE](https://m7.org/docs/api/sso.user.m7.org/quickstart.md) |
| Organization app with its own tenant sign-in/account screens | [Browser-direct setup and endpoint reference](https://m7.org/docs/api/sso.user.m7.org/browser-direct.md) |
| Tenant member authenticator and email-factor settings | [Tenant two-factor authentication](https://m7.org/docs/api/sso.user.m7.org/tenant-two-factor.md) |
| Identity broker or custom protocol integration using M7 consumer identity | [Consumer federation protocol reference](https://m7.org/docs/api/sso.user.m7.org/consumer-federation-reference.md) |
| Implement M7 consumer federation from registration through production | [Consumer federation integration tutorial](https://m7.org/docs/api/sso.user.m7.org/consumer-federation-integration-tutorial.md) |
| Encrypt ID tokens, JARM and signed UserInfo for your app | [Response encryption](https://m7.org/docs/api/sso.user.m7.org/response-encryption.md) |
| Handle authorization success, cancellation, and errors | [Authorization callback outcomes](https://m7.org/docs/api/sso.user.m7.org/authorization-callback-outcomes.md) |
| High-assurance browser request handoff | [Pushed Authorization Requests](https://m7.org/docs/api/sso.user.m7.org/authorization-requests.md#pushed-authorization-requests-par) |
| Sign authorization parameters before browser delivery | [Signed Request Objects (JAR)](https://m7.org/docs/api/sso.user.m7.org/authorization-requests.md#signed-request-objects-jar) |
| Consumer sign-in with an emailed link or code | [Email sign-in](https://m7.org/docs/api/sso.user.m7.org/email-sign-in.md) |
| TV, CLI, or input-constrained device | [Device authorization](https://m7.org/docs/api/sso.user.m7.org/device-authorization.md) |
| Service-to-service access without a user | [`client_credentials`](https://m7.org/docs/api/sso.user.m7.org/token.md#client-credentials) |
| Evaluate an inbound machine or personal admin owner proxy | [Receiver principal-list ACL](https://m7.org/docs/api/sso.user.m7.org/authorization.md#inbound-machine-principal-list-acl) |
| Call a connected service on a user's behalf | [Token Exchange (RFC 8693)](https://m7.org/docs/api/sso.user.m7.org/token.md#token-exchange-rfc-8693) and [current-source SDK integration](https://m7.org/docs/sdk/m7-identity/cli/token-exchange) |
| Distinguish token subject, requesting client and receiving app | [Access-token claims](https://m7.org/docs/api/sso.user.m7.org/token-formats.md#requesting-client-and-receiving-application) |
| Verify an M7 API key received by a resource | [API-key verification](https://m7.org/docs/api/sso.user.m7.org/api-key-verification.md) |
| Receive application logout notifications | [Logout notifications](https://m7.org/docs/api/sso.user.m7.org/logout-notifications.md) |
| Create an OAuth client programmatically | [Dynamic client registration](https://m7.org/docs/api/sso.user.m7.org/registration.md) |
| Account or organization management after sign-in | [M7 User API](https://m7.org/docs/api/api.user.m7.org/) |

For hosted user sign-in, use authorization code with PKCE and send the browser
to `/authorize`; M7 chooses the sign-in and consent experience. Applications
using that flow do not collect passwords. Opted-in organization applications
can instead use the separate [browser-direct tenant protocol](https://m7.org/docs/api/sso.user.m7.org/browser-direct.md)
with mandatory DPoP and PKCE. Its HTTP routes are distinct from hosted forms.

M7 owns the browser pages at `/login`, `/email-sign-in`, `/signup`, and
`/device_login`. Do not POST to them or treat their form-processing routes as an application API.

## Endpoints

| Purpose | Endpoint | Documentation |
| --- | --- | --- |
| Discovery | `GET /.well-known/openid-configuration` | [Discovery and signing keys](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md) |
| Signing keys | `GET /jwks.json` and `GET /cert/kid/{kid}?response=pem` | [Signing-key set](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#signing-key-set) |
| Authorization | `GET /authorize` | [Authorization requests](https://m7.org/docs/api/sso.user.m7.org/authorization-requests.md) |
| Pushed authorization request | `POST /par` | [PAR](https://m7.org/docs/api/sso.user.m7.org/authorization-requests.md#pushed-authorization-requests-par) |
| Token | `POST /token` | [Token endpoint](https://m7.org/docs/api/sso.user.m7.org/token.md) |
| Device authorization | `POST /device_authorization` | [Device authorization](https://m7.org/docs/api/sso.user.m7.org/device-authorization.md) |
| UserInfo | `GET` or `POST /userinfo` | [UserInfo](https://m7.org/docs/api/sso.user.m7.org/userinfo.md) |
| Consumer organizations | `GET` or `POST /userinfo/orgs` | [UserInfo: consumer organizations](https://m7.org/docs/api/sso.user.m7.org/userinfo.md#consumer-organizations) |
| Receiving-service organization facts | `POST /introspect/orgs` | [Recipient-authenticated lookup (current source; deployment verification pending)](https://m7.org/docs/api/sso.user.m7.org/userinfo-orgs.md#receiving-service-organization-lookup) |
| Dynamic registration | `POST /register` | [Registration](https://m7.org/docs/api/sso.user.m7.org/registration.md) |
| Token introspection | `POST /introspect` | [Token lifecycle](https://m7.org/docs/api/sso.user.m7.org/lifecycle.md#introspection) |
| Receiver principal-list ACL | `POST /introspect/acl` | [Machine and personal owner-proxy authorization](https://m7.org/docs/api/sso.user.m7.org/authorization.md#inbound-machine-principal-list-acl) |
| Manage attached ACL members | `POST /acl/members/upsert` | [ACL membership management (local implementation; deployment pending)](https://m7.org/docs/api/sso.user.m7.org/acl-membership.md) |
| Token revocation | `POST /revoke` | [Token lifecycle](https://m7.org/docs/api/sso.user.m7.org/lifecycle.md#revocation) |
| End session | `GET` or `POST /end-session` | [Token lifecycle](https://m7.org/docs/api/sso.user.m7.org/lifecycle.md#end-session) |
| Refresh-package acknowledgement | `POST /token/ack` | [Token acknowledgement](https://m7.org/docs/api/sso.user.m7.org/token-acknowledgement.md) |
| API-key verification | `POST /api-key/verify` | [API-key verification](https://m7.org/docs/api/sso.user.m7.org/api-key-verification.md) |
| Browser-direct tenant operations | `/browser-direct/{CLIENT_ID}/*` | [Complete route-family map](https://m7.org/docs/api/sso.user.m7.org/browser-direct.md#reference-map) |

## Logout and session revocation

Browser-direct has separate carrier logout and member/application device
revocation. Use its [scope matrix](https://m7.org/docs/api/sso.user.m7.org/browser-direct-sessions.md); the hosted
logout delivery described here is not a browser-direct push-notification promise.

Front- and back-channel logout are deployed and advertised. Explicit SSO logout
and the account chooser's logout × notify registered participating applications
after root-family revocation. Ordinary account switching sends none. Both
channels always carry `sid`; the browser channel also carries `iss`.

See [logout notifications](https://m7.org/docs/api/sso.user.m7.org/logout-notifications.md) for setup and delivery
limits, and [User API sessions](https://m7.org/docs/api/api.user.m7.org/sessions)
for remote root-session revocation. The current Web/PHP SDK back receiver
validates and acknowledges notifications only; application-session invalidation
and further SDK tuning remain separate work.

## Consumer two-factor authentication

Users can manage their authenticator, independent sign-in checks, recovery
codes, and unlink options in [M7 two-factor settings](https://user.m7.org/members/settings/2fa).
Applications use the normal hosted sign-in flows. See
[two-factor authentication](https://m7.org/docs/api/sso.user.m7.org/two-factor-authentication.md) for password,
email sign-in, Device Code, remembered-account, silent-sign-in, and recovery
behavior.

[Email sign-in](https://m7.org/docs/api/sso.user.m7.org/email-sign-in.md) offers a magic link and one-time code in
one message, with explicit link confirmation in the original browser and an
independent Email sign-in two-factor setting.

## Response encryption

Registered RSA-OAEP-256/A256GCM encryption is deployed for ID tokens, JARM and
signed UserInfo. A dedicated PHP receiver passed the inline-key RS256 browser,
strict-refresh and cancellation path on 2026-09-16. Upgrade the receiver and
register only its public key before requiring encryption. See the
[setup and validation guide](https://m7.org/docs/api/sso.user.m7.org/response-encryption.md).

## Supported protocol features

- Authorization response: `code` using any of the ten registered and advertised
  [response modes](https://m7.org/docs/api/sso.user.m7.org/response-modes.md): query, form POST, fragment, signed
  JARM, or Web Message. Query is the default; iframe use needs provider approval.
- Grant types: `authorization_code`, `refresh_token`, `client_credentials`,
  `urn:ietf:params:oauth:grant-type:device_code`, and
  `urn:ietf:params:oauth:grant-type:token-exchange` (the scoped profile above).
- PKCE: required for authorization-code exchange; use `S256`.
- Client authentication: `none`, `client_secret_basic`, `client_secret_post`,
  `client_secret_jwt`, `private_key_jwt`, `tls_client_auth`, and
  `self_signed_tls_client_auth`, subject to the client's configured method.
- OpenID Connect scopes: `openid`, `profile`, `email`, `groups`, and
  `offline_access`. A client may also have application-specific allowed
  scopes.
- Authorization: `/token` returns `token_type: "Bearer"` for an unbound access
  token and `token_type: "DPoP"` when the token contains a valid `cnf.jkt`
  sender constraint. Discovery advertises ES256, Dynamic Registration accepts
  `dpop_bound_access_tokens`, and authorization supports `dpop_jkt` directly
  and through PAR. Each registered client can use `disabled`, `optional`, or
  `required` DPoP policy at `/token`; a DPoP-bound lineage also requires the
  exact endpoint-specific authorization scheme and fresh matching proofs at
  protected resources. See the
  [project-specific authorization guide](https://m7.org/docs/api/sso.user.m7.org/authorization.md#dpop-status).
- Mutual TLS: discovery advertises RFC 8705 client authentication,
  certificate-bound access tokens, and dedicated endpoint aliases. The
  canonical issuer remains `https://sso.user.m7.org`. See the
  [provider profile](https://m7.org/docs/api/sso.user.m7.org/provider-profile.md#mutual-tls-client-authentication).

## Important M7 extensions

M7 uses standard OAuth and OpenID Connect endpoint shapes where possible, but
some token packages have additional security material:

- App-bound access tokens carry the issuer-owned `m7.target_client_id` for the
  receiving app. `client_id` identifies the requester; these differ during
  Token Exchange. The resource audience set also includes the target UUID.
- User-facing token packages can include `binding_chain` and `binding_link`.
  Treat them like refresh-token secrets and retain them with the refresh token.
- A refresh may use the M7 `refresh_mode` extension. The normal default is
  strict rotation. Only integrations designed for durable pending-state
  handling should select an acknowledgement mode.
- `/token/ack` activates a pending ACK-mode replacement package. It is not a
  generic token endpoint.
- `/userinfo` derives the owning `client_id` from the validated access token.
  An optional request `client_id` is only a legacy exact-match assertion and
  cannot override the token.
- `/jwks.json` publishes the 15 asymmetric provider-signing profiles using
  `RSA`, `EC`, `OKP`, and `AKP` keys. Each `x5u` remains on the SSO origin and
  resolves through `/cert/kid/{kid}?response=pem`. Personal-lineage keys are
  available by exact `kid` and are not enumerated in provider JWKS.
- ID-token algorithm selection requires agreement between client registration,
  live discovery and the consumer's verifier. Both discovery documents advertise
  all 18 profiles: 15 asymmetric plus HS256/384/512, verified at
  2026-09-15 21:49:24 UTC. HMAC is for confidential clients, uses a recoverable
  client secret and has no public key. The `none`/HMAC eligibility guard is
  locally tested; deployment verification remains pending. See
  [HMAC setup and client repair](https://m7.org/docs/api/sso.user.m7.org/registration.md#hmac-token-signing).
  Updated M7 SDK source supports optional native verification; published
  ZIPs remain unchanged. ML-DSA device/native
  use is distinct from the current Web SDK cookie-size limitation. See
  [signing profiles](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#signing-profiles) and
  [post-quantum storage](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#post-quantum-tokens-and-browser-storage).

## Shared request rules

Use HTTPS. Token-like endpoints accept
`application/x-www-form-urlencoded` bodies unless their page says otherwise.
`/register` and `/token/ack` require JSON bodies. `/api-key/verify` accepts a
Bearer header or one `key` field in a JSON or form body, plus optional
`audience` and `scope` expectations, and is intentionally absent from OAuth
discovery. JSON API errors use the OAuth error shape:

```json
{
  "error": "invalid_request",
  "error_description": "an explanation suitable for the integrator"
}
```

These protocol endpoints operate on one authorization transaction or
credential at a time and do not use pagination.

Never log access tokens, refresh tokens, `binding_chain`, `binding_link`,
client secrets, DPoP proofs, or token-ack activation secrets. Use a secure
server-side store for confidential-client credentials and refresh packages.

## Local conformance assessment

The [15 October 2026 reconciliation](https://m7.org/docs/api/sso.user.m7.org/conformance-reconciliation-2026-10-15.md)
accounts for all 86 selected local cases. It separates recorded technical
passes from presentation/extension decisions and deferred validation; it is
not a certification or a current-code full-suite pass.

## Guides

- [M7 OAuth 2.0 and OpenID Connect Provider Profile](https://m7.org/docs/api/sso.user.m7.org/provider-profile.md)
- [M7 provider capability card](https://m7.org/docs/api/sso.user.m7.org/provider-capabilities.md)
- [Authorization response modes](https://m7.org/docs/api/sso.user.m7.org/response-modes.md)
- [Quickstart: authorization code with PKCE](https://m7.org/docs/api/sso.user.m7.org/quickstart.md)
- [M7 consumer identity federation protocol reference](https://m7.org/docs/api/sso.user.m7.org/consumer-federation-reference.md)
- [Tutorial: integrate M7 consumer identity as a federated provider](https://m7.org/docs/api/sso.user.m7.org/consumer-federation-integration-tutorial.md)
- [Authorization and credential lifecycle](https://m7.org/docs/api/sso.user.m7.org/authorization.md)
- [Access-token formats](https://m7.org/docs/api/sso.user.m7.org/token-formats.md)
- [Authorization requests, PAR, and JAR](https://m7.org/docs/api/sso.user.m7.org/authorization-requests.md)
- [Authorization callback outcomes](https://m7.org/docs/api/sso.user.m7.org/authorization-callback-outcomes.md)
- [Token endpoint and grants](https://m7.org/docs/api/sso.user.m7.org/token.md)
- [Device authorization](https://m7.org/docs/api/sso.user.m7.org/device-authorization.md)
- [Email sign-in: magic link or one-time code](https://m7.org/docs/api/sso.user.m7.org/email-sign-in.md)
- [Two-factor authentication and recovery](https://m7.org/docs/api/sso.user.m7.org/two-factor-authentication.md)
- [UserInfo and scopes](https://m7.org/docs/api/sso.user.m7.org/userinfo.md)
- [Dynamic client registration](https://m7.org/docs/api/sso.user.m7.org/registration.md)
- [Discovery and signing keys](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md)
- [Token lifecycle and logout](https://m7.org/docs/api/sso.user.m7.org/lifecycle.md)
- [Acknowledgement-mode refreshes](https://m7.org/docs/api/sso.user.m7.org/token-acknowledgement.md)
- [API-key verification](https://m7.org/docs/api/sso.user.m7.org/api-key-verification.md)
- [Inbound machine principal-list ACL](https://m7.org/docs/api/sso.user.m7.org/authorization.md#inbound-machine-principal-list-acl)
- [Manage attached ACL members](https://m7.org/docs/api/sso.user.m7.org/acl-membership.md)

## Consumer organizations

Consumer users and ordinary client-credentials apps receive their own live
Management memberships; validated personal admin owner proxies use their
current registered owner’s direct memberships. Results are filtered by the org
owner's default-off, ordered
discovery policy. Registration ownership, membership, disclosure and resource
authorization are separate checks.

- [Consumer org endpoint, caller access projection and failures](https://m7.org/docs/api/sso.user.m7.org/userinfo-orgs.md)
- [Normative organization profile](https://m7.org/docs/api/sso.user.m7.org/provider-profile.md#consumer-organization-discovery)
- [Endpoint and mTLS discovery metadata](https://m7.org/docs/api/sso.user.m7.org/discovery-and-keys.md#organization-endpoint-metadata)
- [SDK website acquisition](https://m7.org/docs/sdk/m7-identity/website/organization-access.md)
- [SDK PHP process acquisition and installation](https://m7.org/docs/sdk/m7-identity/cli/organization-access.md)