JSON Web Tokens & API authentication

A JSON Web Token (JWT) is three base64url-encoded segments separated by dots: a header (naming the signing algorithm), a payload (the claims — arbitrary data such as user ID and expiry), and a signature over the first two segments. The signature can be produced with a symmetric HMAC (HS256) or an asymmetric algorithm like RSA or ECDSA (RS256, ES256).

Here's an actual HS256-signed JWT encoding the claims {"sub": "1234567890", "name": "Alice", "iat": 1516239022}, signed with a symmetric secret. Each of the three segments below decodes with ordinary base64url — paste the first two into any base64 decoder and you'll get readable JSON back; only the third segment (the signature) is opaque, because it's the output of an HMAC, not an encoding of anything.

Verifying a JWT's signature confirms the claims haven't been altered since signing and that they were signed by a holder of the corresponding key — it says nothing about whether the token has since been revoked or is still meant to be valid, which is why expiry (exp) claims and short lifetimes matter. The payload is only encoded, not encrypted: anyone can base64-decode it and read the claims, so secrets never belong there.

This is worth proving to yourself directly, since it's the single most common JWT misconception: base64url is not encryption, it's just an encoding, and reversing it takes no key at all.

The alternative to a JWT is an opaque session token: a random string that means nothing on its own, looked up in a server-side database on every request. The trade-off between them is really a trade-off about where state lives.

The "can't be revoked before expiry" line in the comparison above is worth taking seriously, because it's a real operational gap, not a footnote: once a JWT is issued, it stays valid until its exp claim says otherwise, no matter what happens on the server afterward — a stolen laptop, a fired employee, a compromised API key all leave a window where the already-issued token still works, because there's no server-side record to delete the way there is for an opaque session token.

The standard real-world fix doesn't abandon JWTs — it limits the blast radius. Issue a short-lived JWT access token (commonly 5–15 minutes) for the actual API calls, paired with a long-lived opaque refresh token that is looked up server-side, exactly like a traditional session token, whenever the client needs a new access token. Revoking access now means revoking the refresh token — instant, just like an opaque token — while the worst an attacker can do with a stolen access token is use it until its own short expiry runs out.

Production signing keys get rotated periodically, for the same reasons any key does — but a verifier needs to know which of possibly several active public keys produced a given token, especially during the overlap window while an old key is still valid for already-issued tokens and a new key is signing fresh ones. The kid (Key ID) field in a JWT's header names exactly which key was used.

Verifiers resolve that kid against a JWKS (JSON Web Key Set) — a JSON document, typically published at a well-known endpoint, listing every currently valid public key by its kid. Rotating a signing key becomes: publish the new public key in the JWKS alongside the old one, start signing new tokens with the new key, and only remove the old public key from the JWKS once every token it ever signed has expired — seamless rotation with zero downtime and no already-issued token ever breaking early.