Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.pleo.io/llms.txt

Use this file to discover all available pages before exploring further.

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 authorisation 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

EnvironmentEndpoint URI
Staginghttps://auth.staging.pleo.io/oauth/token/introspect
Productionhttps://auth.pleo.io/oauth/token/introspect

​
Authentication Requirements

The introspection endpoint requires client authentication using HTTP Basic Authentication:
  • client_id as the username
  • client_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:
ParameterDescription
tokenREQUIRED – The access token (or refresh token) to introspect
token_type_hintOPTIONAL – access_token or refresh_token

​
Introspection Response

The response is a JSON object containing token metadata.
FieldDescription
activetrue if the token is currently valid
subSubject the token represents
expExpiration time (UNIX timestamp)
iatIssued-at time (UNIX timestamp)
client_idClient that requested the token
audIntended audience(s)
issToken issuer
jtiToken identifier
urn:pleo:params:oauth:subject_urnPleo-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"
}