Auth API reference

Auth API · Consumer-Verify

post/{app_slug}/v1/verify

Verify a token signature + return its principal

Validates the JWT against the app's JWKS keys and returns `{ valid, principal }`. Use this when you need the full claims; use `/authorize` for a yes/no permission check. Token source: `body.token` if provided, else the `Authorization: Bearer <jwt>` header. At least one must be present.

Path parameters

app_slug*string

Slug of the app.

Request body

tokenstring

EndUser or M2M JWT to verify against the app JWKS. Optional — if omitted, the token is read from the `Authorization: Bearer <jwt>` header instead.

Example: "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiJ1c3JfMSJ9.c2lnbmF0dXJl"

Response · 200

valid*boolean

True iff the signature, issuer, audience AND the backing session are all valid. For `end_user` tokens the session must exist, be unrevoked and be unexpired, and the account row must still exist and be active — a deleted end user is never `valid: true`, even inside the access token's own `exp` window.

errorstring

Failure code on `valid: false`. `TOKEN_INVALID` — signature / issuer / audience / app mismatch, an `end_user` token with no `sid` claim, or an `end_user` token whose account row no longer exists. `TOKEN_EXPIRED` — the token's own `exp` has passed. `TOKEN_REVOKED` — the backing session was revoked (sign-out, password change, admin revoke) or its row no longer exists because the end user was deleted. `SESSION_EXPIRED` — the session row is past `expires_at`; the access token outlived the session that minted it. `ACCOUNT_SUSPENDED` — the account exists but its status is not `active`.

principalobject
sub*string

Subject — EndUser account id or M2M client id.

aid*string

App UUID this token is bound to.

rolestring

App-level role name when EndUser.

permissionsarray

Permission claim — only set on M2M tokens.

type*string

Principal type, e.g. `end_user` or `m2m`.

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/verify
Content-Type: application/json

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiJ1c3JfMSJ9.c2lnbmF0dXJl"
}

Response

{
  "valid": false,
  "error": "string",
  "principal": {
    "sub": "string",
    "aid": "string",
    "role": "string",
    "permissions": [
      "string"
    ],
    "type": "string"
  }
}