How to Read a JWT: Decoding Tokens to Debug Authentication Problems
By the Super Simple Digital Tools Team · Updated June 2026
When an authentication flow breaks, the token itself is usually the best witness. A JSON Web Token is three Base64URL-encoded sections joined by dots, and decoding the first two gives you a direct look at what the issuing server actually put inside. Instead of adding print statements or digging through server logs, you can paste the token into a decoder and immediately see the algorithm, the claims, and the timestamps. That single step resolves a surprising share of login and API failures, because most of them come down to a value being wrong, missing, or expired.
Start with the header. It is small, typically just two fields: alg, the signing algorithm such as HS256 or RS256, and typ, almost always JWT. The header matters more than it looks. If your backend expects RS256 but the token says HS256, signature verification will fail no matter how correct the payload is. The header is also where algorithm-confusion attacks hide, so confirming alg is the value your system intends is a quick and worthwhile sanity check before you look anywhere else.
The payload is where the answers usually live. Look at sub to confirm the token is about the right user, iss to confirm it came from the issuer you trust, and aud to confirm it was meant for your service rather than another. Then check the timing claims. exp and iat are Unix timestamps in seconds, and a common bug is a token that is technically valid but expired, or one whose nbf (not before) time is still in the future because of clock skew between servers. Comparing exp to the current time explains most premature logouts.
It is worth repeating what a decoder does not do. It never tells you whether a token is authentic, because it does not check the signature. A token whose payload reads perfectly could still be forged, and a decoder will happily display it anyway. Authenticity depends on recomputing the signature with the correct key, and that verification must happen where the key lives: your server or a trusted local tool. Treat decoding as reading the token's claims, and verification as a separate, key-dependent step that no public web page should perform.
Finally, build a habit around privacy. Because the payload is plainly readable, a token is effectively a small unencrypted document containing whatever the issuer chose to include, often user identifiers and scopes. For day-to-day debugging in development, decoding tokens in the browser is convenient and fine. For anything touching production, decode locally or scrub the token down to a harmless example. The goal is to get the diagnostic value of seeing inside the token without ever handing a live credential to a page you do not fully trust.
- Always check the alg field in the header first; a mismatch with what your backend expects is a frequent cause of failed verification.
- Convert exp and iat from Unix seconds to a real date and compare exp against the current time to diagnose 'why did my session end early' bugs.
- If a token is rejected despite looking valid, check nbf and account for clock skew between the issuing and validating servers.
- Never decode a live production token in a tool you don't control; replace real values with dummy data, or decode it on your own machine.