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

export const RememberCallout = ({title, children}) => <div className="callout-box callout-remember">
    <div className="callout-row">
      <span className="callout-icon">
        <svg width="22" height="22" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M229.66,98.34,172.39,155.8c11.46,22.93-1.72,45.86-10.11,57a8,8,0,0,1-12,.83L42.34,105.76A8,8,0,0,1,43,93.85c29.65-23.92,57.4-10,57.4-10l57.27-57.46a8,8,0,0,1,11.31,0L229.66,87A8,8,0,0,1,229.66,98.34Z" opacity="0.2" /><path d="M235.32,81.37,174.63,20.69a16,16,0,0,0-22.63,0L98.37,74.49c-10.66-3.34-35-7.37-60.4,13.14a16,16,0,0,0-1.29,23.78L85,159.71,42.34,202.34a8,8,0,0,0,11.32,11.32L96.29,171l48.29,48.29A16,16,0,0,0,155.9,224c.38,0,.75,0,1.13,0a15.93,15.93,0,0,0,11.64-6.33c19.64-26.1,17.75-47.32,13.19-60L235.33,104A16,16,0,0,0,235.32,81.37ZM224,92.69h0l-57.27,57.46a8,8,0,0,0-1.49,9.22c9.46,18.93-1.8,38.59-9.34,48.62L48,100.08c12.08-9.74,23.64-12.31,32.48-12.31A40.13,40.13,0,0,1,96.81,91a8,8,0,0,0,9.25-1.51L163.32,32,224,92.68Z" /></svg>
      </span>
      <div>
        {title && <div className="callout-title">
            {title}
          </div>}
        <div className="callout-body">
          {children}
        </div>
      </div>
    </div>
  </div>;

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      |

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

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