--- title: /oauth2/introspect description: Use the /oauth2/introspect endpoint to retrieve details about OAuth 2.0 tokens, including scopes, user information, expiry time, and proof-of-possession keys component: pingam version: 7.5 page_id: pingam:am-oauth2:oauth2-introspect-endpoint canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-introspect-endpoint.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["OAuth 2.0", "Endpoints", "Scope", "JWT", "Grant Flow", "REST API"] page_aliases: ["varlist-oauth2-introspect-endpoint.adoc", "oauth2-guide:oauth2-introspect-endpoint.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-introspect-endpoint.html section_ids: example: Example introspection_requirements: Introspection requirements special_tokens: Special tokens response_signing_and_encryption: Response signing and encryption rfc-9701-token-introspection-claim: RFC 9701 token_introspection claim response_content: Response content --- # /oauth2/introspect The `/oauth2/introspect` endpoint, defined in RFC 7662 [OAuth 2.0 Token Introspection](https://www.rfc-editor.org/info/rfc7662), lets a client (including resource servers) retrieve details about a token. These details include: * 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 client making the request must authenticate to this endpoint. Specify the realm in the request URL. For example: ```none https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/introspect ``` The default settings for this endpoint don't 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](../reference/deployment-configuration-reference.html#org.forgerock.openam.introspect.token.query.param.allowed) advanced server property. The token introspection endpoint supports the following parameters: | Parameter | Description | Required | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `client_assertion` | A signed JSON Web Token (JWT) to use as client credentials. | Yes, for [JWT profile](client-auth-jwt.html) authentication | | `client_assertion_type` | The type of assertion, `client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer`. | Yes, for [JWT profile](client-auth-jwt.html) authentication | | `client_id` | Uniquely identifies the application making the request. | Yes | | `client_secret` | The password for a confidential client. | Yes, when authenticating with [Form parameters (HTTP POST)](client-auth-form.html) | | `token` | The token to introspect. | Yes | | `token_type_hint` | A hint about the type of token to introspect. Valid values are `access_token`, `refresh_token`, and `requesting_party_token`. | No | ## Example The following example demonstrates token introspection: ```bash $ curl \ --request POST \ --user "myClient:forgerock" \ --data "token=" \ "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/introspect" { "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://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha", "auth_level": 0, "authGrantId": "sReMmkL05mN4xtDMQdVrpjXB_go", "auditTrackingId": "1d7a3317-03a9-4461-9d12-745f886019c2-5860187", "expires_in": 3575 } ``` ## Introspection requirements A client can only introspect a token if it meets one of the following requirements: * Has a special scope The client has a [special introspection scope](oauth2-scopes.html#special-oauth2-scopes) (`am-introspect-all-tokens` or `am-introspect-all-tokens-any-realm`) specified in its client profile. * Token was issued to the client (server-side tokens) For server-side tokens, AM compares the `clientID` field stored in the token against the `client_id` of the client. If they match, the client can introspect the token. By default, the `clientID` field is set to the client that originally requested the token. * Token audience includes the client (client-side tokens) For client-side tokens, AM checks if the `client_id` of the client is present in the `aud` (audience) claim. If there's a match, the client can introspect the token. By default, the `aud` claim is set to the client that originally requested the token. ### 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. PingAM also supports signed JWT (JSON Web Token) or signed and encrypted JWT introspection responses, as defined in [RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/info/rfc9701). Regardless of the configured response format, a client can request a signed JWT response by adding one of the following headers to the introspection request: * `Accept:application/jwt` (default, for compatibility with older clients) * `Accept: application/token-introspection+jwt` (for compatibility with [RFC 9701](#rfc-9701-token-introspection-claim)) To enable signing and encryption for all requests to a client, 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 list. 2. If you need to configure signing and encryption algorithms, set 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. ## RFC 9701 token_introspection claim By default, PingAM returns a flat JWT introspection response for backwards compatibility with older clients. To comply with RFC 9701, enable the Use token_introspection claim for JWT setting. To enable the `token_introspection` claim, you can configure it at two levels: * **Realm level**: In the AM admin UI, go to Realms > *realm name* > Services > OAuth2 Provider > Advanced, and select Use token_introspection claim for JWT. * **Client level**: In the AM admin UI, go to Realms > *realm name* > Applications > OAuth 2.0 > *client ID* > OAuth2 Provider Overrides. Enable OAuth2 Provider Overrides, then select Use token_introspection claim for JWT. When enabled, PingAM wraps the introspected token's claims inside a `token_introspection` claim in the JWT. This separates the JWT's own top-level claims (such as `iss`, `aud`, and `iat` for the introspection response itself) from the introspected token's claims: ```json { "iss": "", "aud": "", "iat": 1234567890, "token_introspection": { "active": true, "scope": "profile", "client_id": "myClient", "aud": ["myClient", "api.example.com"], "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da", "exp": 1675703376 } } ``` When enabled, the `aud` claim of the introspected token is always included in the response, including for stateless (client-side) tokens. When disabled, the `aud` claim is omitted from the response, and a flat JWT structure is used. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This setting is disabled by default to preserve existing behavior after upgrades. Enable it for new deployments or when your resource servers are ready to consume RFC 9701-compliant responses. | ## Response content The following table describes fields you may find in the introspection response: | Field | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `active` | Whether the token is active (`true`) or not (`false`). | | `auth_level` | The AM authentication level for the resource owner who granted access to the token. | | `client_id` | The client the token was issued to. | | `cnf` | The confirmation key claim.The `jwk` type contains the decoded JWK for the access token in the [JWK-based proof-of-possession](oauth2-PoP-JWK.html) flow. | | `exp` | Expiration time in seconds since January 1, 1970 UTC. | | `expires_in` | Expiration time in seconds from now; the value decreases with every request to PingAM.Unlike the calculated value, the expiration time stored in the token does not change.For client-side tokens, PingAM only returns this to a client in the same realm as the resource owner. | | `iss` | The token issuer. | | `macaroon` | The macaroon the token validates, including any caveats. | | `permissions` | (UMA only) An array containing the following:- RPT token expiration time (`exp`) - Resource scopes of the token - Resource ID | | `scope` | The space-separated list of the scopes associated with the token. | | `sub` | 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)`. | | `token_type` | The type of token. | | `user_id` | Deprecated form of `username`. | | `username` | The user who authorized the client to obtain the token. |