How to debug JWT payloads without leaking secrets
JWTs are convenient because they carry structured claims in a compact string. They are also easy to mishandle. A token copied into a chat, ticket or random decoder may contain account identifiers, scopes, tenant names and expiry details. Debugging a JWT safely means separating what you need to inspect from what you should never share.
Remember that decoding is not verification
A JWT decoder can split the token into header, payload and signature, then base64url-decode the JSON sections. That is useful for reading claims, but it does not prove that the token is valid. Signature verification requires the issuer key and the expected algorithm.
This distinction matters in bug reports. Saying “the JWT decodes correctly” only means the token is syntactically readable. It does not mean the token should be accepted by an API.
Inspect claims before sharing anything
The payload often contains fields that identify a user, workspace, plan, organization or environment. Even when the token is expired, those claims may still be sensitive. Read the payload locally first and decide which fields are needed to explain the issue.
- Check `exp`, `nbf` and `iat` to understand time-based failures.
- Check `iss` and `aud` when an API rejects a token from the wrong issuer or audience.
- Check scopes and roles when authorization fails after authentication succeeds.
- Replace `sub`, tenant IDs, emails and internal names before posting examples.
Use synthetic tokens in documentation
Docs and support articles rarely need real tokens. Create a synthetic header and payload that show the relevant claim names, then use a placeholder signature. Readers can understand the shape without seeing production values.
If the bug depends on a precise timestamp or scope value, keep the format and change the content. For example, use a future-looking example timestamp rather than one copied from a live customer token.
Avoid pasting bearer tokens into external tools
A bearer token is effectively a password until it expires or is revoked. If it grants access to a production API, treat it as a secret. Prefer local tooling, internal approved utilities or a browser-only decoder that you can inspect with the network panel.
If a production token was pasted into a place you do not control, rotate it. The safest token is the one that no longer works.
A safe JWT debugging checklist
- Decode locally first and identify only the claims needed for the discussion.
- Never share a live signature or full bearer token in a public issue.
- Redact user, organization, tenant and environment identifiers.
- State whether the problem is parsing, expiry, audience, issuer or authorization scope.
- Rotate any token that may have been exposed outside approved systems.