JWT Debugging: 5 Tasks You'll Hit Daily (and How to Handle Them Without a Library)

Nikhil Sai — Tue, 28 Jul 2026 18:30:00 +0000

JWTs show up everywhere: auth headers, session cookies, API gateways and debugging them usually means someone pasting a token into a random website and hoping it's not logging it. Here are five recurring JWT tasks worth having a fast, trustworthy way to handle.

1. Decoding header and payload

A JWT is just three Base64URL-encoded segments joined by dots header, payload, signature. You don't need a library or an online tool of questionable trustworthiness to read one; you just need something that splits it and renders the header and payload as readable JSON.

function decodeJwt(token) {
  const [headerB64, payloadB64] = token.split(".");
  const decode = (b64) =>
    JSON.parse(atob(b64.replace(/-/g, "+").replace(/_/g, "/")));
  return {
    header: decode(headerB64),
    payload: decode(payloadB64),
  };
}

That's genuinely all a "JWT decoder" does under the hood no signature verification, just structural decoding. Worth knowing so you're never surprised by what one of these tools can and can't tell you.

2. Checking expiry without doing the math

The exp claim is a Unix timestamp, and mentally converting something like 1785340800 into a date is not a good use of anyone's time. Once decoded, new Date(payload.exp * 1000) gets you there but if you're doing this often, having exp, iat, and nbf rendered as human-readable dates next to the raw value saves the mental math every single time.

3. Spotting algorithm mismatches

The alg field in the header (HS256, RS256, none) is a classic attack surface a server that trusts the client-supplied algorithm is vulnerable to alg: none forgery. If you're ever debugging why a token verification is behaving unexpectedly, checking the decoded header's alg field first is a fast sanity check before diving into signature logic.

4. Inspecting custom claims

Most tokens carry more than sub and exp roles, tenant IDs, scopes, feature flags. When a permissions bug shows up in production, decoding the actual token a user has (not the one you assume they have) is usually the fastest way to confirm what's wrong. This is the debugging step people skip most often, and it's the one that actually resolves the bug fastest.

5. Verifying structure before debugging further

"Invalid token" errors are often just malformed input a truncated copy-paste, a missing segment, extra whitespace. Decoding first tells you immediately whether you're dealing with a structurally broken token or a genuine signature/claims problem downstream.

The privacy angle nobody thinks about until it bites them

Here's the thing about JWTs specifically: they often carry live session data, and pasting a production token into a random "jwt decoder" website means that site's server sees your token, even if only in transit. Most of these sites aren't malicious, but you genuinely can't verify that from the UI.

I ended up building a JWT Decoder that runs entirely client-side for exactly this reason you can open dev tools, check the network tab, and confirm nothing gets sent anywhere. It's part of a broader set of ~49 browser-based dev utilities I've been building at Simple Dev Tools.

Quick checklist before you trust a JWT

Decode header + payload, confirm alg matches what your server expects
Check exp hasn't passed and nbf has
Confirm claims match the identity/permissions you expect
Never decode a production token on a site you don't control

Originally published at simpledevtools.org/blog

DEV Community: Nikhil Sai