> Markdown version of https://authpi.com/docs/reference/core-api/token-introspection/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Token Introspection — AuthPI Core API

Validate API keys and personal tokens. Returns token metadata and active status for use by customer backend services.

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/tokens/introspect

**Introspect Token**

Validates an API key or personal token and returns its metadata.

Use this endpoint to determine if a token is currently active and retrieve information about it. This is useful for:

- **Backend services** validating API keys before granting access
- **Applications** checking personal token validity
- **Audit systems** retrieving token metadata

## Token Types

- **API keys** (`key_<id>:<secret>`): Validated via hash comparison against the key's Durable Object. Supports IP allowlist enforcement when `ip` is provided.
- **Personal tokens** (`ptk_<jwt>`): JWT signature is verified first, then the token's status (revoked/blocked/expired) is checked against the Durable Object.

## Response

- `active: true` — Token is valid and can be used. Includes token metadata.
- `active: false` — Token is invalid, expired, revoked, blocked, or not found. Includes `reason`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Required | The token to introspect. Prefix determines type: `key_` for API keys, `ptk_` for personal tokens. |
| `ip` | string | Optional | End-user IP for API key IP allowlist validation. When omitted, IP allowlist checking is skipped. Ignored for personal tokens. |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Token introspection result. `active: true` includes token metadata; `active: false` includes the reason. | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |