How to debug JWT authentication safely
A security-aware workflow for separating token structure, claim validation, signature verification, and authorization decisions.
Decoding a JWT only reveals text supplied by whoever created the token. It does not prove identity, integrity, or server acceptance until the signature and required claims are verified.
Work with sanitized test tokens whenever possible. A production bearer token grants access to whoever obtains it until it expires or is revoked.
Inspect structure and time claims
Confirm the token has three JWS segments and decode header and payload. Check exp, nbf, and iat as Unix seconds, including time zone assumptions and allowed clock skew.
Verify that iss, aud, sub, tenant, client_id, and token type match the exact environment and API receiving the request.
Verify algorithm and signature
The server must allow only expected algorithms and select the correct trusted key. Never accept alg none or choose verification behavior solely from an untrusted header.
For key rotation, inspect kid and the current JWKS set, cache lifetime, and overlap between old and new signing keys.
Separate authentication from authorization
A valid signature does not grant every action. Compare scopes, roles, permissions, resource ownership, and policy decisions with the endpoint requirements.
Record the exact rejection stage and server error without logging the full bearer token.
JWT debugging checklist
- Use a sanitized or short-lived test token.
- Check exp, nbf, iat, and clock skew in Unix seconds.
- Match issuer, audience, environment, and token type.
- Restrict accepted algorithms and verify the signature.
- Check kid and key rotation behavior.
- Validate authorization after authentication succeeds.
Related guides
Learn the workflow behind this tool and what to check next.
How to debug JSON API payloads
A practical workflow for formatting JSON, finding syntax errors, validating payload shape, and checking response status when API data looks wrong.
How to debug an API JSON response step by step
A repeatable workflow for separating transport errors, JSON syntax problems, and data-contract failures in API responses.