Access token introspection allows your integration to verify whether an OAuth 2.0 token is currently valid and retrieve server-authoritative metadata about it.
Introspection is intended for debugging, validation, and internal decision-making. Integrations must not rely on token contents locally, as tokens remain opaque outside of this endpoint. See the Tokens Overview for guidance on token handling expectations.
When to Use Introspection
Use token introspection when you need to:
- Confirm whether a token is still active
- Debug authentication or failures
- Verify scopes or audience during development or support workflows
Do not use introspection as a replacement for normal token lifecycle handling (expiry tracking and refresh).
Token Introspection Endpoint
| Environment | Endpoint URI |
|---|
| Staging | https://auth.staging.pleo.io/oauth/token/introspect |
| Production | https://auth.pleo.io/oauth/token/introspect |
Authentication Requirements
The introspection endpoint requires client authentication using HTTP Basic Authentication:
client_id as the usernameclient_secret as the password
Only the client that obtained the token may introspect it.
Making an Introspection Request
Send an HTTP POST request with application/x-www-form-urlencoded parameters:
| Parameter | Description |
|---|
token | REQUIRED – The access token (or refresh token) to introspect |
token_type_hint | OPTIONAL – access_token or refresh_token |
Introspection Response
The response is a JSON object containing token metadata.
| Field | Description |
|---|
active | true if the token is currently valid |
sub | Subject the token represents |
exp | Expiration time (UNIX timestamp) |
iat | Issued-at time (UNIX timestamp) |
client_id | Client that requested the token |
aud | Intended audience(s) |
iss | Token issuer |
jti | Token identifier |
urn:pleo:params:oauth:subject_urn | Pleo-specific resource identifier |
Introspection reflects current server state. A token may become inactive at any time due to revocation, expiry, or security events.
Example Request
POST /oauth/token/introspect HTTP/1.1
Host: auth.staging.pleo.io
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM
Example Response
{
"active": true,
"sub": "user_12345",
"exp": 1735689600,
"iat": 1735686000,
"client_id": "client_abc",
"aud": ["pleo-api"],
"iss": "https://auth.pleo.io",
"jti": "f1c2d3"
}
