Identity Cloud


The /oauth2/introspect endpoint is defined in RFC 7662 OAuth 2.0 Token Introspection.

A resource server uses this endpoint to retrieve details about a token, such as:

  • The approved scopes

  • The user who authorized the client to obtain the token

  • The expiry time

  • The proof-of-possession JSON Web Key (JWK)

The resource server must authenticate to access this endpoint.

To introspect macaroon access tokens containing third-party caveats, use the X-Discharge-Macaroon header to pass the discharge macaroon.

Specify the realm in the request URL; for example:


The token introspection endpoint supports the following parameters:

Parameter Description Required


A signed JSON Web Token (JWT) to use as client credentials.

Yes, for JWT profile authentication


The type of assertion, client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer.

Yes, for JWT profile authentication


Uniquely identifies the application making the request.



The password for a confidential client.

Yes, when authenticating with Form parameters (HTTP POST)


The token to introspect.



The following example demonstrates token introspection:

$ curl \
--request POST \
--user "myClient:forgerock" \
--data "token=<access-token>" \
  "active": true,
  "scope": "profile",
  "realm": "/alpha",
  "client_id": "myClient",
  "user_id": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "username": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "token_type": "Bearer",
  "exp": 1675703376,
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "subname": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "iss": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha",
  "auth_level": 0,
  "authGrantId": "sReMmkL05mN4xtDMQdVrpjXB_go",
  "auditTrackingId": "1d7a3317-03a9-4461-9d12-745f886019c2-5860187",
  "expires_in": 3575

Response signing and encryption

The default introspection response is a plain JSON object.

Identity Cloud also supports the JWT Response for OAuth Token Introspection Internet-Draft, which adds signed JWT or signed and encrypted JWT responses.

A client application can request a signed JWT by adding an Accept: application/jwt header to the request.

To enable signing and encryption for all requests, follow these steps:

  1. In the Identity Cloud admin UI, go to Applications > Client ID > Sign On > General Settings > Show advanced settings > Endpoint Response Formats and select the response type in the Token Inspection Response Format drop-down list.

  2. Save your work.

  3. If you need to configure signing and encryption, go to Native Consoles > Access Management > Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > Signing and Encryption and configure the following properties:

    Token introspection response signing algorithm

    Default: RS256

    Token introspection response encryption algorithm

    Default: RSA-OAEP-256

    Token introspection encrypted response encryption algorithm

    Default: A128CBC-HS256

  4. Save your work.

Requests for plain JSON now return errors.

Response content

The following table describes fields you may find in the introspection response:

Field Description


Whether the token is active (true) or not (false).


The authentication level for the resource owner who granted access to the token.


The client the token was issued to.


The confirmation key claim.

The jwk type contains the decoded JWK for the access token in the JWK-based proof-of-possession flow.


Expiration time in seconds since January 1, 1970 UTC.


Expiration time in seconds from now; the value decreases with every request to Identity Cloud.

Unlike the calculated value, the expiration time stored in the token does not change.

For client-side tokens, Identity Cloud only returns this to a client in the same realm as the resource owner.


The token issuer.


The macaroon the token validates, including any caveats.


The space-separated list of the scopes associated with the token.


The subject of the access token.

This can use the format (type!subject), where:

  • subject is the principal’s ID.

  • type can be one of the following:


    The subject is an OAuth 2.0 or OpenID Connect client, a Remote Consent Service agent, or a Web or Java Agent internal client.


    The subject is a user, device, or similar identity.

Examples: (usr!demo), (age!myOAuth2Client)


The type of token.


Deprecated form of username.


The user who authorized the client to obtain the token.

Copyright © 2010-2024 ForgeRock, all rights reserved.