# Introspect tokens

When your application needs an authoritative, server-side answer about whether a token should still be accepted, call the [Introspection (`/oidc/token/introspection`)](/openapi/user/oidc.openapi/other/oidcintrospecttoken) 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 cases

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


Choose between ID token, UserInfo, and Introspection
- **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](/guides/user/validate_tokens).


## How it works

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.

```mermaid
sequenceDiagram
  participant A as API or backend
  participant M as Mosaic

  Note over A,M: Token received by backend service
  A->>M: Call `Introspection` with token<br/>using client credentials
  M-->>A: Return active flag and token metadata
  A-->>A: Allow/reject request or continue token flow
```

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.

## Example

In the example below, a trusted backend calls the [Introspection (`/oidc/token/introspection`)](/openapi/user/oidc.openapi/other/oidcintrospecttoken) 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:

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

```json
{
  "active": false
}
```

Handling the response
If the response indicates `active: false`, reject the request and do not rely on any cached authorization decision.

Caching and performance
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.