keepcalculator

06 Numbers and Powers

Decode the JWT First: Stop Guessing at Auth Bugs

Card No. 06·81006 · Updated · Standard formula, shown below

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 exp claim against the current time.
  • Wrong audience — the aud claim doesn’t match your API’s expected value.
  • Wrong issuer — the iss claim points to a different auth server.
  • Missing scopes — the scope or roles claim doesn’t include what the endpoint requires.
  • Signature mismatch — the header says HS256 but your server expects RS256.

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.

  1. 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.
  2. Use a command-line tool — jq can 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" or HS256 when the server expects RS256. An attacker can sometimes forge tokens if the server accepts none.
  • Clock skew — the exp and iat claims 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 exp at 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 Authorization header with the Bearer scheme?
  • 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

The whole Numbers and Powers drawer →