When your application needs an authoritative, server-side answer about whether a token should still be accepted, call the Introspection (/oidc/token/introspection) endpoint.
The Introspection endpoint lets a trusted backend service ask the authorization server whether a token is active and retrieve metadata about that token. In Mosaic, you can use it for both access tokens, which are issued to clients as JWTs, and refresh tokens, which are opaque.
Introspection is typically called by trusted backend systems such as:
- Resource servers that receive access tokens from client applications
- Backend APIs that need to validate incoming user tokens centrally
- Internal services that need a consistent token status check across multiple systems
Use Introspection to:
- Check token activity from a central source
- Enforce revocation-aware token validation
- Keep multiple APIs aligned on a single server-side token decision
- Introspect refresh tokens, which are opaque in Mosaic
- ID token: Use it for identity claims returned directly by the login flow.
- UserInfo (
/oidc/me): Use it to retrieve user claims after token exchange by calling the endpoint with the access token. - Introspection: Use it to check whether an access token is still active and retrieve token metadata for backend or API decisions. If your API consumes self-contained JWT access tokens and needs a low-latency validation path, local JWT validation may still be the better fit; see Validate tokens.
When an app needs to validate an access token or refresh token, it can call Introspection using its own client credentials. Mosaic then returns an authoritative server-side answer about whether the token is active and, when applicable, metadata associated with it.
The response helps your service answer two practical questions: should this token still be accepted, and what token context should be used when processing the request. In addition to the active flag, the response can include metadata such as exp, client_id, sub, and scope. The exact response can vary by token type and configuration, but the core purpose is always the same: give your backend an authoritative token status check together with enough metadata to make an authorization decision.
In the example below, a trusted backend calls the Introspection (/oidc/token/introspection) endpoint with the token it wants to validate.
The standard OAuth 2.0 pattern is to pass the token to introspect as form data, for example token=TOKEN_TO_INTROSPECT, and authenticate the calling service separately using its client credentials.
This separation is important:
- the token being checked represents the end-user or calling client
- the authentication on the Introspection request proves that your backend is allowed to ask for token status.
If the token is active, the response can include metadata such as:
{
"active": true,
"client_id": "pVEZaxFuQyCQ95NNhiBLe",
"sub": "ufnbfps4ki0qm1twdo79g",
"scope": "openid profile payments",
"exp": 1735689600
}If the token is no longer valid, the response should indicate that the token is inactive:
{
"active": false
}If the response indicates active: false, reject the request and do not rely on any cached authorization decision.
Introspection adds a network round-trip. Short-lived caching can reduce latency, but a central check is most useful when you need up-to-date token status. For high-throughput JWT validation paths, local signature validation may still be preferable when centralized status checks are not required.