← Back to all guides

How to Debug a Broken JWT Authentication Flow Step by Step

Published October 20, 2026

A practical walkthrough for figuring out why a JWT-based login is failing — decoding the token to inspect its real claims, understanding what's actually encoded versus encrypted, and building a clean test token to retry against your dev environment.

"The user is logged in, but every API call comes back 401" is one of those bugs that feels like it could be anywhere — the frontend, the backend, the token itself, or the clock on somebody's laptop. The fastest way through it is almost always to stop guessing and go look at the actual token. This walkthrough covers how to do that properly, including the parts that trip people up even after years of working with JWTs.

First, what a JWT actually is

A JSON Web Token (defined in RFC 7519) is three base64url-encoded segments joined by dots: header.payload.signature. A realistic one looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfOGQzZjAyIiwicm9sZSI6ImVkaXRvciIsImlhdCI6MTc2MTAwMDAwMCwiZXhwIjoxNzYxMDAzNjAwfQ.4f3e2b1a9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f

That's a wall of noise unless you break it apart, which is exactly what JWT Decoder is for. Paste the token in and it splits it into the three parts and decodes the first two for you:

// header
{
  "alg": "HS256",
  "typ": "JWT"
}

// payload
{
  "sub": "usr_8d3f02",
  "role": "editor",
  "iat": 1761000000,
  "exp": 1761003600
}

The header tells you which algorithm was used to sign the token (HS256 here — HMAC with SHA-256). The payload is the actual claims: who this token represents (sub), whatever custom data the issuer decided to include (role), when it was issued (iat, an issued-at Unix timestamp), and when it expires (exp). This is usually where a "why am I getting 401s" investigation gets solved in under a minute — paste the token, look at exp, convert it to a real date, and discover it expired eleven minutes ago while the frontend kept using it anyway.

The misconception that causes real security bugs: encoded is not encrypted

This is the single most important thing to understand about JWTs, and it's also the thing that gets gotten wrong most often, sometimes with real consequences. The header and payload are base64url-encoded, not encrypted. Encoding is not a secret-keeping mechanism — it's just a reversible text transformation, the same category of thing as representing a number in hexadecimal instead of decimal. Anyone who has the token — including a user inspecting their own browser's network tab or local storage — can decode the payload and read every claim in it instantly, with no key, no password, and no cracking required.

What the signature actually protects is integrity, not confidentiality. The signature lets the server verify that the payload hasn't been tampered with since it was issued — because computing a valid signature requires the server's secret key (for HMAC algorithms) or private key (for RSA/ECDSA algorithms), which the client never has. But the signature says nothing about who's allowed to read the payload, because reading it never required a key in the first place.

The practical consequence: never put anything in a JWT payload that you wouldn't be comfortable showing to the end user directly — no passwords, no raw internal database IDs you're trying to keep private, no secrets of any kind. If you need confidentiality, not just integrity, you need an encrypted token format (JWE) or you need to not put the sensitive data in the token at all and look it up server-side instead. A JWT with a valid signature is trustworthy in the sense that it hasn't been altered; it's not private.

Decoding a segment by hand, when you don't trust the tool's output

Occasionally you'll want to verify what a decoder is actually doing, or you'll have a raw segment from a log line or a curl response that you want to decode without pasting a full token anywhere. The payload segment is just standard base64url — base64 with +// replaced by -/_ and padding stripped — so you can decode it directly with Base64 Decode.

Take the payload segment from above, eyJzdWIiOiJ1c3JfOGQzZjAyIiwicm9sZSI6ImVkaXRvciIsImlhdCI6MTc2MTAwMDAwMCwiZXhwIjoxNzYxMDAzNjAwfQ, and run it through the decoder. You'll get back the same raw JSON text shown above. Doing this by hand once or twice is a good exercise precisely because it proves to you that there's no magic in a JWT decoder — it's doing exactly this split-and-decode operation, nothing more. If a decoder tool and a manual base64 decode ever disagree on what a token contains, trust the manual decode and go figure out why the tool is wrong, though in practice this is mostly useful for building confidence rather than catching actual bugs.

One wrinkle worth knowing: standard base64 decoders sometimes choke on JWT segments because of the missing padding (= characters) and the URL-safe character substitutions. A decoder built with JWTs in mind handles this automatically; a generic one might not, which is itself a useful diagnostic if you're ever unsure whether a tool is JWT-aware.

Validating the payload you're about to encode

If the bug is on the issuing side — your backend or test script is producing tokens that the receiving service rejects — the problem is often a malformed payload rather than anything cryptographic. Before encoding a new test token, paste the intended payload into JSON Formatter to confirm it's actually valid JSON. A trailing comma, an unquoted key, or a stray single-quote instead of a double-quote will produce a payload that looks fine in a hastily-written test script but fails validation (or worse, gets silently mis-parsed) on the other end.

This matters more than it sounds like it should, because JWT payloads are frequently hand-edited or templated from string concatenation rather than built through a proper JSON serializer, especially in quick test scripts or curl commands. A formatter catching the syntax error before you encode anything saves you from the much more confusing experience of debugging a signature or claims problem that's actually just broken JSON underneath.

Building a fresh test token

Once you know what the payload should look like — correct claim names, correct exp far enough in the future, correct role or whatever custom claims your app checks — use JWT Encoder to build a token from scratch. Set the header algorithm to match what your dev environment expects (usually HS256 for a shared-secret setup), enter your payload claims, and supply the signing secret your local server is configured with.

This gives you a token you fully control for testing: you know exactly what's in it because you just typed it, so if the API call still fails, you've eliminated "the token itself is malformed" as a possibility and can focus on the actual middleware, the clock skew between services, or a mismatched secret between the token's environment and the verifying environment. A quick sanity sequence that catches most "valid-looking token still gets rejected" bugs:

  1. Is exp actually in the future, in Unix seconds (not milliseconds — a classic off-by-1000x bug that produces a token that "expired" in 1970 or won't expire until the year 50000)?
  2. Does the alg in the header match what the verifying server expects? A server expecting HS256 will reject a token signed with HS384, even with the right secret.
  3. Is the signing secret identical, byte-for-byte, between whatever issued the token and whatever's verifying it — including no accidental trailing whitespace or newline from a .env file?

Why all of this is safe to do with a real token

Everything described here — decoding, base64 operations, JSON validation, encoding — runs entirely in your browser. No step here sends the token, its payload, or any signing secret to a server anywhere. That matters in practice: debugging a real production auth token, or testing with a real signing secret, means that data never needs to leave your machine to get the job done. For anything involving an actual secret key, that's not a nice-to-have, it's the whole reason the tool is usable for this at all.

Recap

  • A JWT is header.payload.signature, each part base64url-encoded, joined by dots — JWT Decoder splits and decodes it for you.
  • The payload is readable by anyone with the token. It is signed, not encrypted — don't put secrets in it.
  • Base64 Decode lets you verify a segment by hand when you want to double-check what a tool is telling you.
  • JSON Formatter catches malformed payloads before you waste time debugging a "signature problem" that's actually a syntax error.
  • JWT Encoder builds a controlled test token so you can isolate whether the problem is the token itself or something downstream.
← Back to all guides