Token Introspection Endpoint

Overview

The Introspection Endpoint is defined in RFC 7662. It allows APIs (or clients) to query the IdP about the active state of an OAuth 2.0 token (Access Token or Refresh Token). Refresh tokens can only be introspected by the client that requested them.

This endpoint is useful for APIs that need to validate whether a token is still valid, and to obtain metadata about the token (e.g., scope, expiration, subject).

Endpoint

The endpoint is advertised in the introspection_endpoint in the metadata exposed by the discovery endpoint and typically is:

POST https://[BASE_URL]/connect/introspect

Parameters (form-encoded)

Parameter Required Description
token Yes The token to be introspected.
token_type_hint Optional A hint about the type of token (access_token or refresh_token).

Authentication

The introspection endpoint requires authentication. Since the request to the introspection endpoint is typically done by an API, which is not an OAuth client, the ApiResource is used to configure credentials. For a client the configured credentials of the client is used.

Response

Successful responses are JSON objects. If the token is active:

{
   "active": true,
   "scope": "openid profile email",
   "client_id": "my-client-id",
   "username": "alice",
   "token_type": "access_token",
   "exp": 1699999999,
   "iat": 1699990000,
   "sub": "6b3d5b7b-867b-4e34-98df-f1c8a9af37b9",
   "aud": "api.example.com",
   "iss": "https://[BASE_URL]" 
}

Unknown or expired tokens will be marked as inactive::

{
   "active": false 
}

Usage Example

HTTP POST /introspect 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic base64(api_resource:api_resource_secret)  

token=[token]&token_type_hint=access_token

Return JWT Instead of JSON

Authway supports RFC 9701 to return a JWT response from the introspection endpoint.

To return a JWT response, set the Accept header in the HTTP request to application/token-introspection+jwt:

HTTP POST /connect/introspect
Accept: application/token-introspection+jwtAuthorization: 
Authorization: Basic base64(api_resource:api_resource_secret)  

token=[token]

A successful response will return a status code of 200 and has a Content-Type: application/token-introspection+jwt header, indicating that the response body contains a raw JWT instead. The base64 decoded JWT will have a typ claim in the header with the value token-introspection+jwt. The token’s payload contains a token_introspection JSON object similar to the default response type:

{
  "alg": "RS256",
  "kid": "BE9D78519A8BBCB28A65FADEECF49CBC",
  "typ": "token-introspection+jwt"
}.{
  "iss": "https://localhost:5001",
  "iat": 1729599599,
  "aud": "api1",
  "token_introspection": {
    "iss": "https://localhost:5001",
    "nbf": 1729599599,
    "iat": 1729599599,
    "exp": 1729603199,
    "aud": [ "api1" ],
    "client_id": "client",
    "jti": "44FD2DE9E9F8E9F4DDD141CD7C244BE9",
    "active": true,
    "scope": "api1"
}}.[Signature]