POST /v1/tokens/verify

POST /v1/tokens/verify

Checks a user token's signature, expiry, app and whether it was signed out. Credential: secret key.

Request

curl -X POST https://api.facecard.dev/v1/tokens/verify \
  -H "Authorization: Bearer fc_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"token":"<jwt>"}'

Response

200 OK for a valid token:

{
  "valid": true,
  "claims": {
    "iss": "https://api.facecard.dev",
    "aud": "facecard",
    "sub": "usr_...",
    "app_id": "app_...",
    "email": "ada@example.com",
    "iat": 1792000000,
    "exp": 1792003600,
    "jti": "..."
  }
}

200 OK for a token that fails verification:

{ "valid": false, "reason": "expired" }

reason is a short string that says why the token was rejected: expired, invalid, revoked (the user signed out with POST /v1/me/logout) or user_not_found. Branch on valid; use reason for messages and logs.

This is the revocation aware check. Offline verification against the JWKS cannot see a sign out.

Errors

To verify without calling the API, use the public keys. See User tokens and JWKS.