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

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](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-token-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      |

<Note>
  Introspection reflects **current server state**. A token may become inactive at any time due to revocation, expiry, or security events.
</Note>

## Example Request

```http theme={null}
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

```json theme={null}
{
  "active": true,
  "sub": "user_12345",
  "exp": 1735689600,
  "iat": 1735686000,
  "client_id": "client_abc",
  "aud": ["pleo-api"],
  "iss": "https://auth.pleo.io",
  "jti": "f1c2d3"
}
```

## Related Reading

* **[OAuth 2.0 Overview](/docs/current/integration-design/auth/oauth/integration-design-auth-oauth-overview)** - introduction to OAuth 2.0 for Pleo integrations
* **[API Keys Overview](/docs/current/authentication/standalone-api-keys-overview)** – alternative authentication method
* **[Tokens Overview](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-token-overview)** – understanding access and refresh tokens
* **[Secure Token Storage](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-secure-token-storage)** – storing credentials securely
* **[Centralised Token Refresh](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-centralised-token-refresh)** – safe token refresh patterns
* **[Race Condition Prevention](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-race-condition-prevention)** – avoid duplicate token refresh attempts
* **[OAuth 2.0 Setup Workflow Guide](/docs/current/guides/oauth-workflow-guide)** - Step-by-step guide to configure OAuth 2.0 for your integration