--- title: /oauth2/introspect description: The /oauth2/introspect endpoint, defined in RFC 7662 OAuth 2.0 Token Introspection, lets a client (including resource servers) retrieve details about a token. These details include: component: pingam version: 8.1 page_id: pingam:am-oauth2:oauth2-introspect-endpoint canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-introspect-endpoint.html keywords: ["OAuth 2.0", "Endpoints", "Scope", "JWT", "Grant Flow", "REST API"] page_aliases: ["varlist-oauth2-introspect-endpoint.adoc", "oauth2-guide:oauth2-introspect-endpoint.adoc"] section_ids: example: Example introspection_requirements: Introspection requirements special_tokens: Special tokens response_signing_and_encryption: Response signing and encryption 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://am.example.com:8443/am/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](../setup/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:mySecret" \ --data "token=" \ "https://am.example.com:8443/am/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://am.example.com:8443/am/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. AM also supports the [JWT Response for OAuth Token Introspection](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-introspection-response-03) 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 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 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. | | `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`. Indicates 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`. Indicates the *subject* is a user/identity.For example, `(usr!bjensen)`, 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. |