JWT, explained

Host0:00Here's the thing that surprises people the first time they really look at a JWT. Take the access token your browser just sent to some API - the one that starts with a long run of gibberish, a dot, more gibberish, a dot, and a final blob. Paste it into any decoder. It opens right up. Header, payload, everything. No password, no key, nothing.

Host0:23That is not a leak. That is the design. A JWT is not encrypted - it is signed. Anyone who can see the token can read every word inside it. What they cannot do is change one letter of it. The entire security of the thing rests on that one distinction: readable by anyone, writable by no one.

Host0:43So the question a resource server asks is never "can I trust this token to be secret?" It is "can I trust that this token was issued by who it says, and that not one byte has changed since?" Answering that question is a checklist, and it runs in a strict order. Let's walk it.

Host1:01The letters J, W, T stand for JSON Web Token, and the name tells you the shape: JSON, carried in three parts separated by dots.

Host1:11Part one is the header. It is a tiny JSON object, and the load-bearing line in it is the algorithm name - it says how the signature in part three was made. Part two is the payload, also JSON, and this is where the actual statements live. Who issued this token - the issuer. Who it is for - the audience. When it expires. What scopes the holder gets. Each statement is called a claim, which is exactly the right word: the token claims these things, and the signature is what makes the claims worth believing.

Host1:43Both of those parts are written in base64url. That is an encoding, not encryption - the same way the envelope on a letter is not a lock. You can decode it by hand. Anyone can.

Host1:55Part three is the signature. And the signature is where the trust actually lives.

Host2:00What does a signature prove? Two things, and it is worth being precise. One: the party named as the issuer held the signing key when this token was made. Two: the header and payload bytes are exactly the bytes that were signed - nothing was swapped, reordered, or appended since.

Host2:18The signature is computed over the header and payload, using a key. Who holds that key decides which of two families you are in.

Host2:27With HS256, one shared secret does both jobs: the same key signs the token and checks the token. That is simple and fast, and it is fine inside one service that trusts itself. The moment more than one party needs to check tokens, a shared secret turns into a liability - everyone who can verify is also everyone who can forge.

Host2:50With RS256, the jobs split. A private key signs; a public key checks. The authorization server keeps the private key and never shares it. Every resource server holds only the public half - so they can all verify, and none of them can mint. That split is why RS256 is the default for anything with more than one service in the room.

Host3:13So the token arrives at an API. What does the API actually do? It runs the resource server's checklist, in order.

Host3:22Parse the token. Check the header's algorithm against policy - and yes, rejecting the "none" algorithm is a real, explicit check, because attackers have used it. Select the right key, using the key ID in the header. Recompute the signature over the exact bytes received and compare. Only then read the claims: not expired, right issuer, right audience, scopes sufficient.

Host3:47Here is the part people miss. Those last checks are not decoration. A token whose signature is perfectly valid but whose claims are wrong - expired yesterday, or issued for a different audience - is a dead token. This is the only two ways a token dies: the signature breaks, or the signature holds and the claims fail. Keep those two classes in your head and every JWT bug report you will ever read sorts itself instantly.

Host4:14A few ways this goes wrong in production, briefly.

Host4:18The "none" algorithm: a token whose header says no signature at all, which naive libraries once accepted. Algorithm confusion: an attacker convinces your checker to treat a token meant for R S 256 as H S 256, and signs it with the public key - which, being public, they have. Lenient expiry checks that let yesterday's token through. And the quietest one: sensitive data written into the payload, then leaked - into logs, into browser storage, into analytics. The token is readable by anyone who holds it. If a claim is a secret, it is in the wrong place.

Host4:57The mental model to keep: a JWT is tamper-evident, not secret. The signature makes the claims trustworthy. It never makes them private.

Host5:07If you want to watch every one of these checks run, that is what the JWT inspector on this site is for. Paste a real token from your own day job - a browser session, a CLI login, an API token - and the console plays the resource server: parse, algorithm policy, key selection, a genuine signature check, then the claims policy. There are six tamper buttons, and they split cleanly into the two death classes: three break the signature, three leave the signature perfectly intact and corrupt the claims instead. Watch which one kills the token, and you will never confuse the two again.