/oauth2/introspect

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.

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:

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

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

Example

The following example demonstrates token introspection:

$ curl \
--request POST \
--user "myClient:forgerock" \
--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
}

Response signing and encryption

The default introspection response is a plain JSON object.

PingOne Advanced Identity Cloud 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:

In the Advanced Identity Cloud admin UI, 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.
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.

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`).
`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 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 PingOne Advanced Identity Cloud. Unlike the calculated value, the expiration time stored in the token does not change. For client-side tokens, PingOne 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!demo)`, `(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).

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

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

For client-side tokens, PingOne 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!demo), (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.