How to inspect JWT auth issues
A JWT troubleshooting flow for checking token claims, time values, permissions, and signing assumptions without treating decoding as verification.
JWT problems often look like generic 401 or 403 responses. The token may be expired, issued for the wrong audience, missing a scope, or signed with an unexpected algorithm.
Decoding helps you inspect claims, but it does not prove the token is valid. Verification still belongs to the system that has the correct key or secret.
Check time-based claims
Inspect exp, iat, and nbf values and convert timestamps into human-readable time.
Consider timezone assumptions and clock skew between clients, servers, CI systems, and identity providers.
Verify issuer, audience, and scopes
Check iss, aud, sub, tenant, client_id, roles, scopes, and permissions against the service that rejects the request.
A token can be well-formed and current but still unauthorized for the endpoint.
Use generated tokens carefully
Generated JWTs are useful for local tests and documentation, but production tokens should come from your auth service.
Use test secrets and harmless sample claims when creating examples.
JWT auth debugging checklist
- Decode the token and inspect header, payload, and algorithm.
- Convert exp, iat, and nbf timestamps.
- Check issuer, audience, subject, scopes, and roles.
- Do not treat decoded content as verified identity.
- Use only test secrets and sample claims for generated tokens.
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 API JSON responses
Format the response, confirm the HTTP status, validate the schema, and compare payload changes before changing application code.