Token lifecycle and logout

This page covers introspection, revocation, and browser end-session behavior. For refresh package rotation and the M7 acknowledgement lifecycle, see Token endpoint and Token acknowledgement.

Introspection

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

Introspection is for a confidential resource server or client that needs the current state of a token it owns. M7 requires the client's configured token endpoint authentication method and rejects public (none) clients for this endpoint.

Field Required Description
token Yes Token to inspect.
token_type_hint No Hint such as access_token or refresh_token.
client_id Conditional Required by body-based and JWT client-authentication methods.

The authenticated client may introspect only a token that was issued to that client. A client-token mismatch returns insufficient_scope with HTTP 403. For client_secret_jwt or private_key_jwt, the client assertion audience is the exact introspection endpoint URL.

Example:

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'

The response contains the token's active state and, when active, its authoritative metadata. Integrations must treat active: false as unusable and must not rely on a decoded JWT alone to establish active status.

{
  "active": true,
  "sub": "SUBJECT_UUID",
  "client_id": "CLIENT_ID",
  "scope": "openid profile",
  "exp": 1786309200
}

Exact optional fields depend on the token class and policy. Do not expose an introspection endpoint to untrusted browser code.

Revocation

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

Revocation requires confidential-client authentication with client_secret_basic or client_secret_post. Send the token to revoke and an optional type hint:

Field Required Description
token Yes Token to revoke. M7 also accepts refresh_token as an alias.
token_type_hint No Hint such as access_token or refresh_token.
client_id Conditional Required for client_secret_post; it may also be included with basic auth if it matches the basic-auth identifier.
client_secret Conditional Required for client_secret_post.

Example with Basic authentication:

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 authenticated client can revoke only its own token. A token that clearly belongs to another client is rejected with insufficient_scope. Follow the response and discard the local token package after a successful revocation.

End session

GET or POST https://sso.user.m7.org/end-session

End session is a browser endpoint. Navigate the user to it to offer and complete sign-out of M7 browser sessions. It accepts these OpenID Connect logout parameters:

Parameter Required Description
id_token_hint No ID token that establishes client context. Strongly recommended.
post_logout_redirect_uri No Exact HTTPS URI registered in this client's post_logout_redirect_uris.
state No Value appended to a validated post-logout redirect.
client_id Conditional Required when using post_logout_redirect_uri without a valid id_token_hint. If both are supplied, it must match the token's client context.
logout_hint No Hint for the logout user experience.
ui_locales No Locale hint for the logout user experience.

Example:

https://sso.user.m7.org/end-session?
  id_token_hint=ID_TOKEN&
  post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&
  state=LOGOUT_STATE

M7 validates the ID token and redirect URI before it exposes a client-scoped return path. If validation fails, it falls back to generic M7 logout instead of redirecting to an untrusted URL. The browser page may let the user select one remembered account or sign out all matching sessions. It then redirects with HTTP 303 to the validated return URL, including state when supplied.

Operational advice

  • Revoke credentials when a user disconnects an application, a device is lost, or a client secret may be exposed.
  • Use introspection for online active-state decisions; cache only within the resource server's documented risk tolerance.
  • Clear your own application session as part of sign-out. M7 end session does not know how to clear cookies or sessions on your domain.
  • Do not put refresh tokens, access tokens, or ID tokens in logout telemetry, redirect logs, or referrer-bearing URLs beyond the standard id_token_hint use described here.