Token Introspection

Introduction

The token introspection endpoint is used to introspect tokens. This is useful when the client requires opaque tokens that are not structured, such that protected resources can request the introspection endpoint and get information about the token. The endpoint supports introspecting access tokens and refresh tokens.

Specifications

Table 1: Specifications
Name	Description
OpenId Connect	Core specification for OpenId Connect
Token Introspection	Specification for introspecting tokens
DPoP	Specification for sender constraining tokens using DPoP
Step up authentication	Step up authentication specification

Token Introspection Endpoint

The token introspection endpoint accepts the POST HTTP method, and the content is application/x-www-form-urlencoded.

The endpoint also requires client authentication, and the parameters are defined in the Client Authentication page.

The endpoint requires client authentication by confidential clients.

The token introspection endpoint returns HTTP 200 if successful, and 400 if an error occurred.

If the token does not exist, is revoked, expired then the token is deemed inactive. If the client is not authorized for any scope of the token, or if the client is not an audience of the token, then the token is deemed inactive.

The following table shows the parameters that can be sent to the endpoint.

Table 2: Token Introspection request parameters
Name	Description
token	The token to be introspected. It is required.
token_type_hint	The type of token to be introspected. It is optional.

Table 3: Token Introspection response parameters
Name	Description
active	Boolean determining if the token is active or not. This is required.
scope	Space delimited string of scopes. This is required if active.
client_id	Id of client that owns the token. This is required if active.
username	Username of the token's subject. This is optional.
token_type	The token's type, which is either Bearer or DPoP. This is required if active.
exp	Unix timestamp when the token expires. This is required if active.
iat	Unix timestamp when the token was issued. This is required if active.
nbf	Unix timestamp when the token is active from. This is required if active.
sub	Subject of the token. Either the end-user or the client. This is required if active.
aud	Array of URIs that may accept the token. This is required if active.
iss	URI of AuthServer. This is required if active.
jti	Unique identifier of the token. This is required if active.
auth_time	Unix timestamp of when the end-user authenticated. This is optional.
acr	The AuthenticationContextReference used when the end-user authenticated. This is optional.
cnf	Object with one field, which is jkt. That is the thumbprint of the DPoP if the token is sender-constrained. This is optional.
access_control	Object with end-user claims used for authorization purposes. This is optional.

The following HTTP example shows a request to introspect an access token.

            
                
POST /connect/introspection HTTP/1.1
Host: idp.authserver.dk
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=23nthgnreag67n

The following HTTP example shows a response with an active dpop bound token and an end-user as the subject.

            
                
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store

{
  "active": true,
  "scope": "scope:read scope:write",
  "client_id": "35d7d4f0-27c8-463c-8057-d39953a16972",
  "username": "john",
  "token_type": "DPoP",
  "exp": 1751708358,
  "iat": 1751708058,
  "nbf": 1751708058,
  "sub": "ec14d771-d1bb-4d0c-9965-8243700a739f",
  "aud": [ "https://api.authserver.dk" ],
  "iss": "https://idp.authserver.dk",
  "jti": "ec26ea37-e612-45f7-8989-612554499117",
  "auth_time": 1751707358,
  "acr": "urn:authserver:loa:substantial",
  "cnf":
  {
    "jkt": "ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"
  },
  "access_control":
  {
    "roles": [ "admin" ]
  }
}

The following HTTP example shows a response with an active bearer token and the client as the subject.

            
                
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store

{
  "active": true,
  "scope": "scope:read scope:write",
  "client_id": "35d7d4f0-27c8-463c-8057-d39953a16972",
  "token_type": "Bearer",
  "exp": 1751708358,
  "iat": 1751708058,
  "nbf": 1751708058,
  "sub": "35d7d4f0-27c8-463c-8057-d39953a16972",
  "aud": [ "https://api.authserver.dk" ],
  "iss": "https://idp.authserver.dk",
  "jti": "ec26ea37-e612-45f7-8989-612554499117"
}

The following HTTP example shows a response with an inactive token.

            
                
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store

{
  "active": false
}