Auth API reference

Auth API · Consumer-Oauth-M2m

post/{app_slug}/v1/oauth/introspectAuth

Introspect 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*string

Slug of the app.

Request body

tokenstring

The 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_hintstring

Optional `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*boolean

Per 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

substring

Subject claim: M2M client id or EndUser account id.

Example: "m2m_a1b2c3d4..."

client_idstring

OAuth `client_id` (M2M only).

Example: "cli_a1b2c3..."

typeobject

Kind of token: `m2m` (client credentials) or `end_user` (a signed-in user). Absent when `active` is false.

scopesarray

Flat scope list (M2M only).

Example: ["user.read","user.list"]

scopestring

Space-separated `scope` string per OAuth 2.0 RFC 6749 — alias of `scopes` joined with " ".

Example: "user.read user.list"

expnumber

Token expiry as Unix timestamp.

Example: 1746906606

iatnumber

Token issued-at Unix timestamp.

Example: 1746903006

issstring

Issuer 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>"

aidstring

App 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"
}