/oauth2/introspect

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:

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:

https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/introspect

The token introspection endpoint supports the following parameters:

Parameter Description Required

Parameter	Description	Required
`client_assertion`	A signed JSON Web Token (JWT) to use as client credentials.	Yes, for JWT profile authentication
`client_assertion_type`	The type of assertion, `client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer`.	Yes, for JWT profile 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)
`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

client_assertion

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

Yes, for JWT profile authentication

client_assertion_type

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

Yes, for JWT profile 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)

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.

Example

The following example demonstrates token introspection:

$ curl \
--request POST \
--user "myClient:mySecret" \
--data "token=<access-token>" \
"https://<tenant-env-fqdn>/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://<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
}

Introspection requirements

A client can only introspect a token if it meets one of the following requirements:

The client has a special scope: The client has a special introspection scope (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, Advanced Identity Cloud compares the issuing client identity stored in the token against the client_id of the introspecting client. If they match, the client can introspect the token.
Token audience includes the client: When the Allow audience members to introspect tokens setting is enabled on the OAuth 2.0 Provider, Advanced Identity Cloud checks if the client_id of the introspecting client is present anywhere in the token’s aud (audience) claim. If there’s a match, the client can introspect the token.

By default, the aud claim contains the requesting client ID for client-side tokens and might be absent for server-side tokens. Token exchange can add audience values when Accept Audience Parameters in Token Exchange Requests is enabled and the requested values are allowed.
The client_id claim matches (client-side tokens only): When the Include client_id claim in stateless access tokens setting is enabled, Advanced Identity Cloud checks whether the client_id JWT claim in the token matches the client_id of the introspecting client. If there’s a match, the client can introspect the token.

Special tokens

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

Response signing and encryption

The default introspection response is a plain JSON object.

Advanced Identity Cloud 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.

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)

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

In the Advanced Identity Cloud admin console, go to Applications > Applications > Name > Sign On > General Settings > Show advanced settings > Endpoint Response Formats and select the response type in the Token Inspection Response Format list.
Save your work.
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
Save your work.

Requests for plain JSON now return errors.

RFC 9701 token_introspection claim

By default, Advanced Identity Cloud 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 Advanced Identity Cloud admin console, go to vpn_key Authorization > OAuth2 Provider > Advanced.
1. Select Use token_introspection claim for JWT.

Client level

Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > OAuth 2.0 > Client ID > OAuth2 Provider Overrides.
Enable OAuth2 Provider Overrides and select Use token_introspection claim for JWT.

If enabled, Advanced Identity Cloud 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:

{
  "iss": "<authorization-server-issuer>",
  "aud": "<resource-server-client-id>",
  "iat": 1234567890,
  "token_introspection": {
    "active": true,
    "scope": "profile",
    "client_id": "myClient",
    "aud": ["myClient", "api.example.com"],
    "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
    "exp": 1675703376
  }
}

The aud claim of the introspected token is always included in the JWT response, including for client-side tokens. The JSON introspection response also includes the aud claim of the introspected token, if present.

If not enabled, Advanced Identity Cloud returns a flat JWT structure. For client-side tokens, the aud claim is omitted from both the JWT response and the JSON response.

This setting isn’t enabled 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

Field	Description
`active`	Whether the token is active (`true`) or not (`false`).
`aud`	The audience of the token. In a JWT response, the top-level `aud` identifies the audience of the introspection response itself. The `token_introspection.aud` claim is the audience claim from the token being introspected.
`auth_level`	The authentication level for the resource owner who granted access to the token.
`authorization_details`	The fine-grained authorization details granted to the token, as specified in RFC 9396: OAuth 2.0 Rich Authorization Requests. Present only if the token was issued with `authorization_details`.
`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 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.

active

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

aud

The audience of the token. In a JWT response, the top-level aud identifies the audience of the introspection response itself. The token_introspection.aud claim is the audience claim from the token being introspected.

auth_level

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

authorization_details

The fine-grained authorization details granted to the token, as specified in RFC 9396: OAuth 2.0 Rich Authorization Requests. Present only if the token was issued with authorization_details.

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

PingOne Advanced Identity Cloud