Two Operations That Look Identical and Aren't
Type "decode JWT" into a search engine and most results will happily display the contents of any token you paste. That experience teaches a dangerous lesson — that reading a token is the same as trusting it. It is not. Decoding a JSON Web Token and verifying it are two entirely different operations with two entirely different security guarantees, and confusing them is behind a large share of authentication vulnerabilities and "it works on my machine" auth bugs. This article draws a hard line between the two, explains exactly what each one does, and shows how to test both in our JWT Decoder & Inspector, which performs verification locally in your browser using the Web Crypto API.
What Decoding Actually Does
A JWT is three base64url-encoded segments separated by dots: header.payload.signature. The encoding is defined in RFC 7515 (JSON Web Signature), §2, and base64url itself comes from RFC 4648 §5 — a URL-safe variant of base64 with no padding requirement in the JWS context. Decoding a JWT means nothing more than splitting on the dots and base64url-decoding the first two segments back into JSON text.
That is the whole operation. It is a reversible transport encoding, not encryption and not a security check. There is no key involved, no math beyond an alphabet lookup, and no possibility of failure other than malformed input. Anyone — including an attacker who intercepts the token — can decode it instantly. This is why RFC 7519 (JSON Web Token) §10.1 warns explicitly that a plain JWS-based JWT offers no confidentiality and the payload must be treated as public.
Decoding answers the question "what does this token claim?" It tells you the algorithm in the header, the iss, aud, sub, and exp claims in the payload, and any custom data your application added. What it cannot tell you is whether any of that is true.
What Verifying Actually Does
Verification is a cryptographic operation. It takes the signing input — the exact bytes base64url(header) + "." + base64url(payload) — and recomputes the signature using a key, then compares the result against the third segment of the token. The algorithms are catalogued in RFC 7518 (JSON Web Algorithms): HMAC variants such as HS256 in §3.2, RSASSA-PKCS1-v1_5 variants such as RS256 in §3.3, and ECDSA variants such as ES256 in §3.4.
Verification answers a completely different question: "was this token issued by someone holding the signing key, and has it been altered since?" If even a single byte of the header or payload changes, the recomputed signature no longer matches and verification fails. That tamper-evidence is the entire point of a JWT. Without verification, the claims are just untrusted text an attacker could have written.
Crucially, verification can fail, and a failure is meaningful. A decode of a forged token succeeds and shows attacker-controlled claims; a verify of that same token fails loudly. That difference — silent success versus a hard cryptographic rejection — is exactly the protection you are throwing away when you treat decoding as validation.
The Mental Model: Reading a Passport vs Authenticating It
Decoding a JWT is like reading the text printed inside a passport. You can see the name, the nationality, the expiry date. Anyone can read a passport, and reading it does not prove it is genuine — a convincing forgery has perfectly readable text too. Verifying the signature is like checking the passport's tamper-proof features against the issuing authority's records. Only that second step tells you the document is authentic and unaltered. A border officer who only read passports without authenticating them would wave through every forgery, and a server that only decodes JWTs without verifying them does precisely the same thing.
Why This Distinction Causes Real Vulnerabilities
Trusting a decoded claim
The classic mistake is decoding a token, reading "role": "admin" from the payload, and granting access — without ever verifying the signature. Because the payload is attacker-readable and attacker-writable before signing, anyone can craft a token whose payload says whatever they want. Decoding it will faithfully show admin. Only verification, against a key the attacker does not possess, rejects the forgery. RFC 8725 (JWT Best Current Practices) §3.1 frames this as the foundational rule: never act on claims from an unverified token.
The "alg: none" downgrade
RFC 7518 §3.6 defines an none algorithm — a JWT with an empty signature, intended only for contexts where integrity is already guaranteed by other means. Early libraries that conflated decode-and-verify would honor whatever the token's header asked for, so an attacker could strip the signature, set "alg": "none", and have the token "verified" against no key at all. RFC 8725 §3.1 and §2.1 call this out directly and require that verifiers pin an expected algorithm rather than trust the header. A pure decoder, by contrast, simply shows you alg: none — it is the verification step that must refuse it.
The HS256/RS256 key-confusion attack
A subtler version, described in RFC 8725 §2.2, exploits a verifier that accepts whatever algorithm the header names. If a service expects RS256 (asymmetric, verified with a public key) but a library lets the token dictate HS256 (symmetric, verified with a shared secret), an attacker can sign a forged token using the public key as if it were the HMAC secret. The public key is, by definition, public. Pinning the expected algorithm during verification defeats this; decoding never could, because decoding does not look at keys at all.
Symmetric vs Asymmetric Verification
How you verify depends on how the token was signed. With a symmetric algorithm like HS256, the same secret both signs and verifies via HMAC (RFC 7518 §3.2, built on RFC 2104). Issuer and verifier must share that secret, which works inside a single trust boundary but does not scale across organizations and means the verifier could also forge tokens. With an asymmetric algorithm like RS256 or ES256, a private key signs and the corresponding public key verifies. This lets an identity provider publish its public key — typically as a JWK Set per RFC 7517 — so any number of services can verify tokens without being able to mint them. The kid header from RFC 7515 §4.1.4 tells the verifier which published key to use. In our JWT Decoder you paste either the HMAC secret or the PEM public key; the browser's Web Crypto API runs the comparison locally and your key never leaves the page.
How to Test Both Operations Safely
The fastest way to internalize the difference is to watch it happen. Open the JWT Decoder & Inspector and try this sequence:
- Decode. Paste any token. The header and payload render immediately, with no key. That is decoding — pure reading.
- Tamper. Change one character in the payload (for example, flip a role or a user id) and re-encode it. Decode again: the new claims display perfectly, because decoding never checks authenticity.
- Verify. Now paste the signing secret or public key and run verification. The original token verifies; the tampered one is rejected. That single red status is the whole reason verification exists.
Because everything runs client-side, you can do this with real tokens without leaking them. That matters: pasting a live session token into a server-side "JWT debugger" transmits a working credential to a third party. RFC 8725 §3.5 stresses minimizing token exposure; a local-only tool is the safe way to honor that while still inspecting production tokens. Pair the decoder with our JSON Formatter when a payload is dense and you want it pretty-printed, and with the Base64 Encoder when you want to hand-decode a single segment to see the raw base64url mechanics for yourself.
A Decision Checklist for Engineers
- Need to read a claim for display or logging? Decoding is fine — but label the data as untrusted.
- Need to make an authorization decision? You must verify first. No exceptions. A decoded claim is attacker-controlled until the signature proves otherwise.
- Pin the algorithm. Configure your verifier with the exact expected algorithm; never let the token's header choose. This neutralizes both
alg: noneand key-confusion attacks. - Validate the standard claims after verifying. A valid signature only proves authenticity. You still must check
exp,nbf,iss, andaudper RFC 7519 §4.1 to confirm the token is meant for you, right now. - Keep keys and tokens local. Verify with a client-side tool so neither your secret nor your live token leaves your machine.
Why Libraries Sometimes Blur the Line
Many JWT libraries expose a single high-level function that decodes and verifies together, which is good — it makes the safe path the default path. The danger appears in libraries (or hand-rolled code) that offer a "decode only" helper for convenience, because developers reach for it to read a claim and then forget that it skipped verification entirely. The naming does not always warn you: a function called decode in one library throws on a bad signature, while in another it never touches the signature at all. When in doubt, read the documentation for that exact function and confirm whether it validates the signature — and if it does, what key it used and what algorithm it pinned. Our decoder keeps the two steps visually separate on purpose, so the distinction the API hides is the one the tool makes obvious.
Conclusion
Decoding tells you what a token says; verifying tells you whether to believe it. Decoding is a keyless, always-succeeding transport transform defined by RFC 7515 and RFC 4648. Verifying is a cryptographic check against a key, governed by RFC 7518 and hardened by the best practices in RFC 8725, and it is the only step that makes a JWT trustworthy. Every serious JWT vulnerability — forged claims, alg: none, key confusion — traces back to code that decoded when it should have verified. Build the habit of asking "did I verify, or did I only decode?" and confirm it with the JWT Decoder & Inspector, which keeps both operations local, explicit, and impossible to confuse. For the broader picture of how tokens are structured and debugged, read our companion guide, JWT Tokens Explained.