Token introspection

What is token introspection?

Token introspection is an OAuth 2.0 extension defined in RFC 7662 that allows clients to query the Authorization server to validate access tokens and retrieve metadata about them. This extension is useful when:

• The client wants to verify the validity of an access token in real-time.
• The access token is opaque (not self-contained) and requires the authorization server to validate it.

How does token introspection work?

Here’s a non-normative example of a token introspection request:

POST /introspect HTTP/1.1
Host: authorization-server.example.com
Content-Type: application/x-www-form-urlencoded

token=random-token-value
  &token_type_hint=access_token

The token_type_hint parameter is optional and should be set to the type of token being introspected. If the access token is valid, the authorization server responds with the token’s metadata:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "scope": "read write",
  "client_id": "client-id",
  "username": "johndoe",
  "token_type": "Bearer",
  "exp": 1634020800,
  "iat": 1634017200
}

It’s worth noting that not all authorization servers support token introspection and not all tokens are introspectable. The Authorization server may limit the use of token introspection based various factors, for example, some authorization servers may not support introspection for JWTs .

Key parameters in a token introspection request

Here are two key parameters in a token introspection request:

• token: The token to introspect.
• token_type_hint: The type of token being introspected. It can be access_token or refresh_token.

See also

• OAuth 2.0
• Opaque token
• JSON Web Token (JWT)