---
title: "Introspect a token"
method: POST
path: "/oauth2/introspect"
tags: ["OAuth Provider"]
---

# Introspect a token

`POST /oauth2/introspect`

OAuth 2.0 Token Introspection Endpoint (RFC 7662).

Check if a token is active and retrieve its metadata.

**Use Cases:**
- Resource servers validating tokens
- Debugging token issues
- Checking token scopes before processing requests

**Response:**
- Active token: Returns `active: true` with token metadata
- Invalid/expired/revoked token: Returns only `active: false`

## Request body

- OAuthIntrospectRequest — OAuth 2.0 Token Introspection Request (RFC 7662). Check if a token is active and get its metadata.
  - `token` string, required — The token to introspect
  - `token_type_hint` 'access_token' | 'refresh_token' — Hint about token type
  - `client_id` string, required — Client ID
  - `client_secret` string — Client secret

## Response `200`

Token introspection result

- OAuthIntrospectResponse — OAuth 2.0 Token Introspection Response (RFC 7662). Contains token metadata if active, or just `active: false` if not.
  - `active` boolean, required — Whether the token is currently active
  - `scope` string — Scopes granted to the token
  - `client_id` string — Client ID the token was issued to
  - `username` string — User identifier (if user-based token)
  - `token_type` string — Token type
  - `exp` integer — Token expiration timestamp (Unix epoch)
  - `iat` integer — Token issuance timestamp (Unix epoch)
  - `nbf` integer — Token not-before timestamp (Unix epoch)
  - `user_id` string — User ID
  - `aud` string — Audience (client ID)
  - `iss` string — Issuer URL
  - `jti` string — Unique token identifier

## Other responses

- `401` — Client authentication failed
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)