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

# Token Management — AuthPI Identity Provider API

Endpoints for token lifecycle management including introspection (RFC 7662) and revocation (RFC 7009). Use these to validate or invalidate tokens.

## POST /{issuer_id}/introspect

**Token Introspection**

Validates a token and returns its metadata (RFC 7662).

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

- **Resource servers** validating access tokens before granting access
- **Applications** checking token validity without decoding the JWT
- **Audit systems** retrieving token metadata

## Authorization

Clients can only introspect tokens they issued. If a client attempts to introspect a token issued to a different client, the response will indicate `active: false` without revealing that the token exists (per RFC 7662 security requirements).

## Response

- `active: true` - Token is valid and can be used
- `active: false` - Token is invalid, expired, revoked, or the client is not authorized to introspect it

When `active: true`, the response includes token claims such as `sub`, `scope`, `exp`, `iat`, and custom claims.

## Token Type Detection

If `token_type_hint` is not provided, the endpoint automatically detects the token type based on its claims. However, providing the hint can improve performance.

**Specification**: [RFC 7662 - OAuth 2.0 Token Introspection](https://tools.ietf.org/html/rfc7662)

### Request body

Content type: `application/x-www-form-urlencoded`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Required | The access token or refresh token to introspect |
| `token_type_hint` | access_token \| refresh_token | Optional | Hint about the token type to optimize lookup. If not provided, the endpoint will attempt to detect the type automatically. |
| `client_id` | string | Optional | Client ID. Required for confidential clients not using HTTP Basic auth. |
| `client_secret` | string | Optional | Client secret, when authenticating via the request body (client_secret_post). |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | **Token Introspection Response** | `IntrospectionResponse` |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |

## POST /{issuer_id}/revoke

**Token Revocation**

Revokes an access token or refresh token (RFC 7009).

Use this endpoint to invalidate tokens when:
- A user logs out
- A user revokes application access
- A token is suspected of being compromised
- Security policies require token invalidation

## Revocation Behavior

**Refresh tokens:** Revocation invalidates the refresh token via the Session Manager. All future attempts to use the token will fail.

**Access tokens:** Revocation adds the token to a revocation list. The token remains technically valid until it expires, but API calls will fail validation. This approach balances security with performance for short-lived tokens.

## Authorization

The client revoking the token must either:
- Be the client that originally requested the token
- Have user credentials with appropriate permissions

## Response

Per RFC 7009, this endpoint always returns a success response (200 OK) regardless of whether the token was valid. This prevents token enumeration attacks.

**Specification**: [RFC 7009 - OAuth 2.0 Token Revocation](https://tools.ietf.org/html/rfc7009)

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `issuer_id` | string | Required | The unique identifier for the issuer/tenant |

### Request body

Content type: `application/x-www-form-urlencoded`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Required | The access token or refresh token to revoke |
| `token_type_hint` | access_token \| refresh_token | Optional | Hint about the token type. Providing this improves performance but is not required. |
| `client_id` | string | Optional | Client ID. Required for confidential clients not using HTTP Basic auth. |
| `client_secret` | string | Optional | Client secret, when authenticating via the request body (client_secret_post). |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | **Success** - Token revoked (or was already invalid). | `object` |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |