⚡ SmartDevTools

How JWTs Work, and Why Decoding Is Not Verifying

By SmarTech Apps · Published 2026-11-18 · 6 min read

A JSON Web Token looks like an opaque blob, but it is three readable pieces joined by dots. Anyone holding the token can read what is inside. What they cannot do, without the right key, is change it undetected. Understanding that difference between reading and trusting is the heart of using JWTs safely.

The three parts

A JWT is header.payload.signature. The header and payload are JSON objects, each encoded with base64url, and the signature is raw bytes, also base64url-encoded. Here is a small token I built and signed with HMAC-SHA256 using the throwaway secret dummy-secret, line-wrapped for reading:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzQy
IiwiYXVkIjoiYXBpLmV4YW1wbGUuY29tIiwiaWF0IjoxNzAwMDAwMDAwLCJleHAiOjE3
MDAwMDM2MDB9
.j1Pf9LgJD_vhVB6q6YXom6qbB4aOVhSHUeD4UQEfvXU

Remove the line breaks and decode the first two segments and you get:

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

// payload
{
  "iss": "https://auth.example.com",
  "sub": "user_42",
  "aud": "api.example.com",
  "iat": 1700000000,
  "exp": 1700003600
}

No key was needed for that. The token expires exactly one hour after it was issued: exp minus iat is 3600 seconds, from 22:13:20 to 23:13:20 UTC on 14 November 2023.

base64url is encoding, not protection

Base64url is base64 with - and _ in place of + and /, and with the trailing = padding removed, so the token is safe in URLs and headers. It is a reversible encoding with no secret involved. You can paste a segment into the Base64 encoder and decoder and read the JSON, after swapping those two characters back if the tool expects standard base64. The longer story is in Base64 is not encryption.

Registered claims

The payload is a set of claims. RFC 7519 defines seven common ones, all optional in the format and all short to keep tokens small:

ClaimMeaning
issIssuer: who created the token
subSubject: who the token is about, usually a user id
audAudience: which service the token is intended for
expExpiry time; reject the token at or after this instant
nbfNot before; reject the token earlier than this instant
iatIssued at
jtiUnique token id, useful for revocation and replay detection

The three time claims are NumericDate values: seconds since the Unix epoch, not milliseconds. A token that never seems to expire, or expires in 1970, usually has milliseconds where seconds belong. The Epoch Time Converter turns them into dates, and Unix timestamps and time zones explains the units.

How the signature works: HS256 versus RS256

The signature covers the exact bytes base64url(header) + "." + base64url(payload). Change one character of either part and the signature no longer matches.

HS256 uses HMAC with SHA-256 and a single shared secret. The same secret signs and verifies, so every service that can verify a token can also mint one. That suits a single application that both issues and checks its own tokens.

RS256 uses RSA with SHA-256. The issuer signs with a private key and publishes a public key, often in a JWKS document, and anyone can verify but only the issuer can sign. It is the better fit when many services, or third parties, must trust one identity provider. ES256 (ECDSA) follows the same pattern with smaller keys and signatures. Choose an algorithm for your system and enforce it on the server rather than reading it from the token.

Attacks: alg=none and algorithm confusion

The header's alg field tells the verifier how the token was signed, and that is attacker-controlled input. Two classic attacks abuse it.

The defence is the same for both: the server supplies an allow-list of algorithms and the key, and never lets the token choose. Reject none unless you explicitly need it, and use a maintained library rather than hand-rolled checking.

What a server must verify

  1. The signature, using an algorithm and key you configured.
  2. exp and, when present, nbf, allowing a small clock skew of a minute or so.
  3. iss equals the issuer you trust.
  4. aud includes your service, so a token minted for another API cannot be replayed against yours.
  5. Any application checks, such as the user still existing and having the required role.

Only after all of these pass should the claims be treated as truth.

Decoding is not verifying

A decoder simply base64url-decodes the first two segments and prints the JSON. It does not check that the signature is genuine. The JWT Decoder here is built for inspection and debugging: it shows the header, payload and signature, and it does not verify the signature, because verification needs the issuer's secret or public key and the tool does not ask for keys. If a token decodes cleanly, that tells you nothing about whether it is authentic. Never make an access decision in client code, or anywhere, based on a decoded but unverified token.

For testing, the JWT Generator lets you edit the header and payload, enter a secret and sign with HS256, HS384 or HS512 so you can produce a token to exercise your own verification code. It does not offer RSA or ECDSA signing. Use made-up secrets there, never real production keys.

Do not put secrets in the payload

Because the payload is only encoded, anything in it is visible to the user, to any proxy that logs headers and to anyone who finds the token in a log or URL. Keep passwords, API keys and personal data out of it. Include an identifier and the minimum claims needed. If confidentiality is truly needed there is an encrypted form, JWE, but that is a different format with its own complexity.

Storage and revocation trade-offs

A signed token is self-contained, so a server can validate it without a database lookup. That is also its weakness: you cannot easily take one back before exp. Common approaches are:

JWTs are a good fit for short-lived, stateless authorisation between services. For ordinary browser sessions, a server-side session id is often simpler and easier to revoke. Whichever you choose, remember the rule that matters most: decoding shows what a token claims, and only verification shows that you can believe it.

Try the tools

Keep reading