AM 7.5.0


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.

Specify the realm in the request URL; for example:

The default settings for this endpoint do not allow:

  • HTTP GET requests

  • Use of token as a query parameter

To change this behavior for compatibility, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

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": "",
  "auth_level": 0,
  "authGrantId": "sReMmkL05mN4xtDMQdVrpjXB_go",
  "auditTrackingId": "1d7a3317-03a9-4461-9d12-745f886019c2-5860187",
  "expires_in": 3575

Introspect special tokens

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

  • To introspect UMA RPT tokens, use the PAT of the resource owner in an authorization: Bearer header to authenticate to the endpoint.

Response signing and encryption

The default introspection response is a plain JSON object.

AM 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 AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Client ID > Advanced and select the response type in the Token introspection response format drop-down list.

  2. If necessary to configure signing and encryption, 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

  3. 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 AM 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 AM.

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

For client-side tokens, AM 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.


(UMA only) An array containing the following:

  • RPT token expiration time (exp)

  • Resource scopes of the token

  • Resource ID


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


The subject of the access token.

The subject claim is in the format (type!subject), where:

  • subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

  • type can be one of the following:

    • age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.

    • usr. Specifies that the subject is a user/identity.

For example, (usr!demo), or (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.