Skip to main content
POST
Introspect an access token
Check whether an access token is still active and retrieve its metadata, such as its scopes and expiry time, before you use it. Authenticate with the client credentials of the OAuth application the token was issued to. The response returns 200 OK for an active token. If a token has expired, been revoked, is unknown, or was issued to a different OAuth application, the response also returns 200 OK, but with "active": false and no other fields, so the response doesn’t reveal anything about tokens that don’t belong to your application. If the token parameter isn’t included in the request, the response returns a 400 Bad Request error. This endpoint is rate limited. Requests that exceed the limit return a 429 Too Many Requests error. Learn more about errors and rate limits.

Authorizations

Authorization
string
header
required

HTTP Basic authentication with the OAuth application's client credentials: the client ID as the username and the client secret as the password, joined with a colon and base64-encoded (Authorization: Basic <base64(client_id:client_secret)>). Tools such as curl encode the credentials for you when you pass them with --user "<client_id>:<client_secret>". Alternatively, send the credentials as the client_id and client_secret form fields in the request body. Don't use both methods in the same request.

Body

application/x-www-form-urlencoded
token
string
required

The access token to introspect.

client_id
string

The client ID of the OAuth application. Use together with client_secret as an alternative to HTTP Basic authentication.

Example:

"H3WVOKGN4B7JXQYCQ6DJFAW5ZU"

client_secret
string

The client secret of the OAuth application. Use together with client_id as an alternative to HTTP Basic authentication.

token_type_hint
enum<string>

A hint about the type of token. Optional; only access tokens are issued.

Available options:
access_token

Response

The token's introspection result.

active
boolean
required

Whether the token is currently active. false for tokens that are expired, revoked, unknown, or issued to a different OAuth application; the remaining fields are omitted in that case.

scope
string

The scopes granted to the token, separated by spaces.

Example:

"users.view users.suspend users.reactivate"

client_id
string

The client ID of the OAuth application the token was issued to.

Example:

"H3WVOKGN4B7JXQYCQ6DJFAW5ZU"

sub
string

The subject of the token. For client credentials tokens, this is the client ID.

Example:

"H3WVOKGN4B7JXQYCQ6DJFAW5ZU"

token_type
string

The token type. Always Bearer for active tokens.

Example:

"Bearer"

exp
integer<int64>

When the token expires, as a Unix timestamp in seconds.

Example:

1760000900

iat
integer<int64>

When the token was issued, as a Unix timestamp in seconds.

Example:

1760000000