/{app_slug}/v1/oauth/introspectAuthIntrospect the bearer access token (RFC 7662)
OAuth 2.0 token introspection. Send the access token via `Authorization: Bearer <token>` and receive either `{ active: false }` (invalid / expired / wrong app, or a session that is revoked, past its `expires_at`, or gone because the end user was deleted) or the active claim set including `scopes` (M2M) or `role` (EndUser), `exp`, `iat`, `iss`, `aid`. The body `token` field is optional and, if present, must match the bearer — RFC 7662 allows a separate `token` body field but we deliberately refuse cross-token introspection so a stolen token can't be probed against another active credential. The endpoint accepts both M2M and EndUser tokens — use it as the canonical way for a service to know what its own token can do, instead of decoding the JWT by hand. Returns 401 when the bearer is missing.
Path parameters
app_slug*stringSlug of the app.
Request body
tokenstringThe access token to introspect. Optional — when omitted the endpoint introspects the `Authorization: Bearer` token. When present, it must match the bearer (we refuse cross-token introspection so a stolen token cannot be probed against a different active credential).
Example: "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiJ1c3JfMSJ9.c2lnbmF0dXJl"
token_type_hintstringOptional `token_type_hint` per RFC 7662. We only issue access tokens at this endpoint so the only meaningful value is `access_token`; the field is accepted for client-library compatibility.
Example: "access_token"
Response · 200 Either `{ active: true }` with the claim set, or `{ active: false }` and nothing else.
active*booleanPer RFC 7662: `true` if the token is currently active for this app, `false` otherwise. An inactive response is the default for any token we can't validate — invalid signature, expired, revoked / expired / deleted session, wrong app — and intentionally carries no other claims so an attacker can't probe the token's shape.
Example: true
substringSubject claim: M2M client id or EndUser account id.
Example: "m2m_a1b2c3d4..."
client_idstringOAuth `client_id` (M2M only).
Example: "cli_a1b2c3..."
typeobjectKind of token: `m2m` (client credentials) or `end_user` (a signed-in user). Absent when `active` is false.
scopesarrayFlat scope list (M2M only).
Example: ["user.read","user.list"]
scopestringSpace-separated `scope` string per OAuth 2.0 RFC 6749 — alias of `scopes` joined with " ".
Example: "user.read user.list"
expnumberToken expiry as Unix timestamp.
Example: 1746906606
iatnumberToken issued-at Unix timestamp.
Example: 1746903006
issstringIssuer URL — the public Auth API base joined with this app slug. Pin this in your local JWKS verifier so a token minted for another app on the platform cannot pass.
Example: "https://api.auth.productcraft.co/<appSlug>"
aidstringApp UUID this token is bound to.
Example: "app-uuid"
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/oauth/introspect
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiJ1c3JfMSJ9.c2lnbmF0dXJl",
"token_type_hint": "access_token"
}Response
{
"active": true,
"sub": "m2m_a1b2c3d4...",
"client_id": "cli_a1b2c3...",
"type": {},
"scopes": [
"user.read",
"user.list"
],
"scope": "user.read user.list",
"exp": 1746906606,
"iat": 1746903006,
"iss": "https://api.auth.productcraft.co/<appSlug>",
"aid": "app-uuid"
}