POST/api/oidc/introspectPublic

Token introspection

The OAuth 2.0 token introspection endpoint (RFC 7662), advertised as introspection_endpoint. The caller POSTs a token issued by this server and learns whether it is currently active plus its metadata (scope, client, subject, expiry), including who is calling as far as the token says: service_account for a machine subject, and the RFC 8693 actor (act) of a token delegated to, e.g., an agent acting for the user. Two kinds of caller may introspect, each only its own tokens: a confidential client app, the OIDC surface's access and refresh tokens issued to it; and an API server (private_key_jwt with its JWKS access key), the access tokens minted for it (its id or one of its RFC 8707 resource URLs as aud), so it can learn about logouts, password resets, disabled accounts and de-authorized apps that local token verification cannot see. Tokens the caller may not see (another client's or another API server's), tokens of a client app the user has since de-authorized or (for API servers) that is no longer connected to the API server, expired and revoked tokens all yield { "active": false }. Public (PKCE-only) clients cannot introspect: without client authentication the endpoint would be open to token scanning. Responses carry Cache-Control: no-store and Access-Control-Allow-Origin: *.

operationId post_api_oidc_introspectOpenID Connect / OAuth 2.0

Authentication & permissionsPublic

Anyone — no credentials required

Accepted credentials: None required
Notes: Client authentication is REQUIRED (RFC 7662 §2.1): client_secret_basic (HTTP Basic Authorization header) or client_secret_post (client_secret form field) of an app with a registered client secret, or private_key_jwt (client_assertion_type + client_assertion form fields) of an API server with an active JWKS access key. The handler performs this itself; none is not accepted.

Request body

Required

application/x-www-form-urlencoded

OidcIntrospectionRequest

Property	Type	Description
token*	string	REQUIRED. The access or refresh token to introspect.
token_type_hint	"access_token" \| "refresh_token"	Accepted but unused: the token kind is read from the token itself.
client_id	string \| string	The confidential client's app id (may be omitted with `client_secret_basic`), or the API server id with `private_key_jwt` (optional; must equal the assertion's `iss`).
client_secret	string	`client_secret_post` authentication.
client_assertion_type	"urn:ietf:params:oauth:client-assertion-type:jwt-bearer"	`private_key_jwt` authentication (RFC 7523 §2.2), for API servers.
client_assertion	string	`private_key_jwt`: a JWKS access assertion signed with the API server's JWKS access key (`createJwksAccessProofToken()` from `@schemavaults/jwt`; `iss` = `sub` = the API server id, `aud` = the issuer, single-use `jti`).

Responses

Header	Type	Description
Cache-Control	string

application/json

OidcIntrospectionResponse

RFC 7662 §2.2 introspection response.

JSONExample

"active"false

Example request

bashcurl

curl -X POST 'https://auth.schemavaults.com/api/oidc/introspect' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=string' \
  --data-urlencode 'token_type_hint=access_token' \
  --data-urlencode 'client_id=string' \
  --data-urlencode 'client_secret=string' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=string'

Authentication & permissionsPublic

Request body

Responses

200The token's state

400Not form-encoded, token missing, malformed client_id, a malformed Basic Authorization header, more than one client authentication method, or an unsupported client_assertion_type / missing client_assertion (invalid_request)

401No client identified, the client secret is wrong, the client is not confidential, or the client assertion does not verify against the API server's active JWKS access key (invalid_client)

500The introspection request could not be processed (server_error)

Example request