M7 SSO API reference

Connect to M7 Identity

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

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

Live discovery supplies endpoint locations and advertised capabilities. Use the provider profile for the integration contract and current testing status.

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:

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.

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

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

Use the M7 account application to manage accounts, organizations, linked identities, OAuth applications, and API keys. The M7 User API 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
Scan the current compatibility surface Provider capability card
Browser, server-rendered web app, SPA, or native app Authorization code with PKCE
Organization app with its own tenant sign-in/account screens Browser-direct setup and endpoint reference
Tenant member authenticator and email-factor settings Tenant two-factor authentication
Identity broker or custom protocol integration using M7 consumer identity Consumer federation protocol reference
Implement M7 consumer federation from registration through production Consumer federation integration tutorial
Encrypt ID tokens, JARM and signed UserInfo for your app Response encryption
Handle authorization success, cancellation, and errors Authorization callback outcomes
High-assurance browser request handoff Pushed Authorization Requests
Sign authorization parameters before browser delivery Signed Request Objects (JAR)
Consumer sign-in with an emailed link or code Email sign-in
TV, CLI, or input-constrained device Device authorization
Service-to-service access without a user client_credentials
Evaluate an inbound machine or personal admin owner proxy Receiver principal-list ACL
Call a connected service on a user's behalf Token Exchange (RFC 8693) and current-source SDK integration
Distinguish token subject, requesting client and receiving app Access-token claims
Verify an M7 API key received by a resource API-key verification
Receive application logout notifications Logout notifications
Create an OAuth client programmatically Dynamic client registration
Account or organization management after sign-in M7 User API

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 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
Signing keys GET /jwks.json and GET /cert/kid/{kid}?response=pem Signing-key set
Authorization GET /authorize Authorization requests
Pushed authorization request POST /par PAR
Token POST /token Token endpoint
Device authorization POST /device_authorization Device authorization
UserInfo GET or POST /userinfo UserInfo
Consumer organizations GET or POST /userinfo/orgs UserInfo: consumer organizations
Dynamic registration POST /register Registration
Token introspection POST /introspect Token lifecycle
Receiver principal-list ACL POST /introspect/acl Machine and personal owner-proxy authorization
Token revocation POST /revoke Token lifecycle
End session GET or POST /end-session Token lifecycle
Refresh-package acknowledgement POST /token/ack Token acknowledgement
API-key verification POST /api-key/verify API-key verification
Browser-direct tenant operations /browser-direct/{CLIENT_ID}/* Complete route-family map

Logout and session revocation

Browser-direct has separate carrier logout and member/application device revocation. Use its scope matrix; 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 for setup and delivery limits, and User API 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. Applications use the normal hosted sign-in flows. See two-factor authentication for password, email sign-in, Device Code, remembered-account, silent-sign-in, and recovery behavior.

Email sign-in 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.

Supported protocol features

  • Authorization response: code using any of the ten registered and advertised response modes: 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.
  • 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.

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. 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 and post-quantum 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:

{
  "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.

Guides

Consumer organizations

Consumer users and ordinary client-credentials apps receive their own live Management memberships, filtered by the org owner's default-off, ordered discovery policy. Registration ownership, membership, disclosure and resource authorization are separate checks.