Yes — when you’re debugging an authentication failure, decode the JWT first instead of guessing at the cause. Most JWT-related bugs (expired tokens, wrong audience, signature mismatch) become obvious the moment you look at the payload and header. This article explains why decoding first saves time, how to do it safely, and what to check after you see the token’s contents.
Why Decoding First Beats Guessing
Authentication bugs have a handful of common causes, and most of them are visible in the token itself. If you guess, you might spend an hour checking your database lookup when the real problem is that the token expired ten minutes ago. Decoding first tells you:
- Expired — check the
expclaim against the current time. - Wrong audience — the
audclaim doesn’t match your API’s expected value. - Wrong issuer — the
issclaim points to a different auth server. - Missing scopes — the
scopeorrolesclaim doesn’t include what the endpoint requires. - Signature mismatch — the header says
HS256but your server expectsRS256.
All of these are visible in the decoded header and payload. You don’t need to trace code to know the token is expired — the exp claim tells you instantly.
How to Decode a JWT Safely
You can decode a JWT in a few ways, but the safest is to use a local tool or a library in your own environment. Avoid pasting real tokens into random websites — they might log the token, and if it’s still valid, that’s a security leak.
- Use your language’s JWT library — most have a
decode()method that doesn’t verify the signature. For example, in Node.js,jwt.decode(token)returns the payload without checking the signature. - Use a command-line tool —
jqcan decode base64url, or you can use a small script.
Always decode before verifying. If you try to verify first and the signature fails, you won’t see the claims that might explain why (e.g., the token was signed with a different algorithm).
Common Problems You’ll See After Decoding
Once you have the decoded header and payload, look for these specific issues:
- Algorithm confusion — the header says
alg: "none"orHS256when the server expectsRS256. An attacker can sometimes forge tokens if the server acceptsnone. - Clock skew — the
expandiatclaims are based on the server’s clock, not your local machine. If the server’s clock is off by a few minutes, a token might appear expired when it isn’t. - Missing claims — the payload might not contain
expat all, which means the token never expires (or the server treats it as invalid).
Common Misconceptions
“Decoding a JWT is the same as verifying it.” No. Decoding just reads the base64-encoded JSON. Anyone can decode a JWT. Verification checks the signature using the secret or public key. Decoding first is safe because you’re not trusting the token — you’re just looking at its contents.
“If the token decodes, it’s valid.” Not at all. A decoded token is just a JSON object. An attacker can create a token with any claims they want, but they can’t create a valid signature without the key. Decoding tells you what the token claims, not whether those claims are trustworthy.
Alternatives to Decoding First
Sometimes you can’t decode first because the token is malformed — it doesn’t have three parts, or the base64 is invalid. In that case, you should:
- Check the token format — does it start with
eyJ? That’s the base64url of{". - Check the request headers — is the token in the
Authorizationheader with theBearerscheme? - Check the server logs — the auth middleware might be rejecting the token before it even reaches your code.
But for 90% of auth bugs, decoding first gives you the answer in seconds.
Frequently Asked Questions
Is it safe to decode a JWT on a public website?
No. If you paste a real token into a random website, you’re sending it to a third party. Even if the token is expired, it might contain sensitive claims.
What does the “alg” in the header mean?
It tells you the signing algorithm. Common values are HS256 (HMAC with SHA-256, uses a shared secret), RS256 (RSA with SHA-256, uses a private key to sign and a public key to verify), and ES256 (ECDSA). If the algorithm is none, the token isn’t signed at all — that’s a security risk.
Why does my token decode but still fail verification?
Decoding doesn’t verify the signature. The signature is computed from the header and payload using a secret or key. If the signature doesn’t match, the token has been tampered with, or your server is using a different key than the one that signed the token. Check the alg and ensure the key is correct.
What is the difference between “exp” and “iat”?
iat is the issued-at time (when the token was created), and exp is the expiration time (when the token becomes invalid). Both are Unix timestamps in seconds. If exp is missing, the token might be considered valid forever, depending on the server’s configuration.
Can I decode a JWT without a library?
Yes. The token is just three base64url-encoded strings separated by dots. You can decode the first two with any base64 decoder (remember to replace - with + and _ with /). The signature is binary and not meant to be decoded.
What should I do if the token has an “aud” claim that doesn’t match my API?
That means the token was issued for a different audience (e.g., a different service or client). Your server should reject it. If you’re testing, make sure the token is generated with the correct audience. If you’re debugging a production issue, check the auth server’s configuration to ensure it’s issuing tokens with the right audience.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Funny Subreddits That Make You Laugh
- Why Retro Gaming Is Still Worth Playing Today
- Skip Ryobi and Milwaukee? Harbor Freight Tools to Buy
- Neptune Facts That Will Blow Your Mind
- Survival Crafting Game Fatigue: Why & How to Fix It
- Sell Your EV Now Before Prices Plummet?