--- title: /oauth2/introspect description: The /oauth2/introspect endpoint is defined in RFC 7662 OAuth 2.0 Token Introspection. component: pingoneaic page_id: pingoneaic:am-oauth2:oauth2-introspect-endpoint canonical_url: https://docs.pingidentity.com/pingoneaic/am-oauth2/oauth2-introspect-endpoint.html keywords: ["OAuth 2.0", "Endpoints", "Scope", "JWT", "Grant Flow", "REST API"] page_aliases: ["oauth2-guide:varlist-oauth2-introspect-endpoint.adoc", "oauth2-guide:oauth2-introspect-endpoint.adoc"] section_ids: example: Example response_signing_and_encryption: Response signing and encryption response_content: Response content --- # /oauth2/introspect The `/oauth2/introspect` endpoint is defined in RFC 7662 [OAuth 2.0 Token Introspection](https://www.rfc-editor.org/info/rfc7662). 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: ```none https:///am/oauth2/realms/root/realms/alpha/introspect ``` 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/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/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. Advanced Identity Cloud 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 Advanced Identity Cloud admin console, 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 | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `active` | Whether the token is active (`true`) or not (`false`). | | `auth_level` | The 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 Advanced Identity Cloud.Unlike the calculated value, the expiration time stored in the token does not change.For client-side tokens, Advanced Identity Cloud 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. | | `scope` | The space-separated list of the scopes associated with the token. | | `sub` | 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: * `age` The *subject* is an OAuth 2.0 or OpenID Connect client, a Remote Consent Service agent, or a Web or Java Agent internal client. * `usr` The *subject* is a user, device, or similar identity.Examples: `(usr!bjensen)`, `(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. |