Access Token Introspection

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

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

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"
}

OAuth 2.0 Overview - introduction to OAuth 2.0 for Pleo integrations
API Keys Overview – alternative authentication method
Tokens Overview – understanding access and refresh tokens
Secure Token Storage – storing credentials securely
Centralised Token Refresh – safe token refresh patterns
Race Condition Prevention – avoid duplicate token refresh attempts
OAuth 2.0 Setup Workflow Guide - Step-by-step guide to configure OAuth 2.0 for your integration

Get Started

Authentication and Authorisation

Platform Capabilities & Concepts

Integration Design

Workflow Guides

How-to's

GLOSSARY

ARCHIVED

Access Token Introspection

When to Use Introspection

Token Introspection Endpoint

Authentication Requirements

Making an Introspection Request

Introspection Response

Example Request

Example Response

​When to Use Introspection

​Token Introspection Endpoint

​Authentication Requirements

​Making an Introspection Request

​Introspection Response

​Example Request

​Example Response

​Related Reading

When to Use Introspection

Token Introspection Endpoint

Authentication Requirements

Making an Introspection Request

Introspection Response

Example Request

Example Response

Related Reading