Introspect a token

RFC 7662, for confidential apps: whether one of the app's own tokens is active now.

POST/oidc/introspect

Access: Private code required
Client: Local or server client

JSON body#

Name	Location	Meaning
`token`Required	JSON	The token.

Request examples#

cURL

curl -fsS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$ACCESS_TOKEN" "https://veil.rip/oidc/introspect"

Response#

HTTP 200application/json

{active, …}; {active: false} for any token not active or not the app's.

Field	Type	Meaning
`active`	`boolean`	Not revoked, not rotated, not expired, the card open and not suspended.
`scope, client_id, sub, aud, iss, iat, exp, token_type, auth_time`	`mixed`	As RFC 7662 names them, when active.
`veil_good_standing`	`boolean`	The card's standing now, when active.

Response headers#

Header	Value	Meaning
`Content-Type`	`application/json`	JSON, also for errors.
`Cache-Control`	`no-store`	Private: never cached.

Usage notes#

Errors of this endpoint follow OAuth: {"error", "error_description"} (RFC 6749, 5.2), not the error object of the rest of the API. A rate limit still answers 429 with the usual envelope.

Errors#

API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide

HTTP Code Meaning and next step

400

HTTP	Code	Meaning and next step
400	`invalid_request`	OAuth error: a parameter is missing, given twice or malformed, or the body is not a form. Read `error_description`, fix the request and send it again.
401	`invalid_client`	OAuth error: the app could not be authenticated, with the method it registered. Check the client id and secret (Basic), the client assertion (private_key_jwt, a new jti each time) or client_id for a public app.

invalid_request

OAuth error: a parameter is missing, given twice or malformed, or the body is not a form.

Read error_description, fix the request and send it again.

401

invalid_client

OAuth error: the app could not be authenticated, with the method it registered.

Check the client id and secret (Basic), the client assertion (private_key_jwt, a new jti each time) or client_id for a public app.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON