---
title: "Introspect a Token"
method: POST
path: "/oauth/v2/introspect"
tags: ["OAuth 2.0"]
---

# Introspect a Token

`POST /oauth/v2/introspect`

## Request

- Base URL: `https://api.proof.com`
- URL: `https://api.proof.com/oauth/v2/introspect`
- Auth: none declared

Returns the state of a token, per [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662). Callers authenticate as the client the token was issued to, or as the protected resource the token was issued for, with [`client_secret_post`](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1), [`client_secret_basic`](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1), [`private_key_jwt`](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2) or a [Bearer token](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1). Expired, revoked and unknown tokens return `active: false`.

## Request body `application/x-www-form-urlencoded`

- IntrospectionRequest
  - `token` string, required: The token to introspect.
  - `token_type_hint` 'access_token' | 'refresh_token': A [`token_type_hint`](https://datatracker.ietf.org/doc/html/rfc7009#section-2.1) for the submitted token.
  - `client_id` string: Your [`client_id`](https://datatracker.ietf.org/doc/html/rfc6749#section-2.2).
  - `client_secret` string: Your client secret, for [`client_secret_post`](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1) client authentication.
  - `client_assertion_type` 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer': Set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` for [`private_key_jwt`](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2) client authentication.
  - `client_assertion` string: A JWT signed with one of your registered keys, for [`private_key_jwt`](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2) client authentication: `iss` and `sub` are your `client_id`, `aud` is the issuer or the token endpoint URL, with `exp` and a single-use `jti`.

## Response `200`

successful

- IntrospectionResponse
  - `active` boolean, required: Whether the token is currently active, per the [introspection response](https://datatracker.ietf.org/doc/html/rfc7662#section-2.2). `false` stands alone.
  - `scope` string: Space-separated [scope](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) values granted to the token.
  - `client_id` string: The [`client_id`](https://datatracker.ietf.org/doc/html/rfc6749#section-2.2) the token was issued to.
  - `token_type` string: Always `Bearer`.
  - `iat` integer: The [`iat`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) claim: issue time, as a Unix timestamp in seconds.
  - `exp` integer: The [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) claim: expiry, as a Unix timestamp in seconds. Present for tokens that expire.
  - `iss` string: The [`iss`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) claim: the authorization server that issued the token.
  - `aud` string: The [`aud`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) claim: the protected resource the token was issued for. Present for resource-bound tokens.
  - `sub` string: The [`sub`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) claim: the subject the token was issued for.
  - `sub_type` string: The kind of subject `sub` identifies.

## Other responses

- `401`: Unauthorized

---

[API](https://skmtc.dev/proof/apis/oauth-2-0-api-specification.md) - [All operations](https://skmtc.dev/proof/apis/oauth-2-0-api-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/proof/apis/oauth-2-0-api-specification/revisions/7e769f9c96ed?raw)