A JSON Web Token (JWT) is a compact, URL-safe representation of claims to be transferred between two parties. Defined in RFC 7519 and ratified in 2015, JWTs are now the dominant token format for stateless authentication and authorization on the web , they power OAuth 2.0 access tokens, OpenID Connect identity tokens, server-to-server API authentication, single sign-on (SSO) implementations, password reset links, email verification flows, and the session tokens of countless modern applications. The format's design lets a server hand the client a small string that proves identity and authorization without the server needing to remember anything about the session , a property that makes JWTs excellent for horizontally scaled systems but also surfaces an unusual set of security pitfalls.

A JWT consists of three Base64URL-encoded segments separated by dots: header.payload.signature. The header declares the signing algorithm (HS256, RS256, ES256, EdDSA) and optionally a key identifier. The payload is a JSON object containing claims , standardized fields like 'iss' (issuer), 'sub' (subject), 'aud' (audience), 'exp' (expiration time), 'nbf' (not before), 'iat' (issued at), and 'jti' (JWT ID), alongside any application-specific claims like user roles, account IDs, or feature flags. The signature is a cryptographic proof, computed over the encoded header and payload using the secret or private key identified in the header, that lets recipients verify the token has not been tampered with. Decoding the token reveals the header and payload as readable JSON; the signature itself is binary and rarely human-meaningful.

This decoder focuses on inspection, not verification. Decoding a JWT only reveals what is inside the token; it does not prove the token is valid. Signature verification , confirming that the token was issued by the expected key holder and has not been modified , requires the public key (for RS256, ES256, EdDSA) or shared secret (for HS256) of the issuing party, and is intentionally not part of the inspection workflow. That separation is by design: inspection is the right tool when you are debugging what an existing token contains; verification is the right tool when your application is enforcing access. Mixing the two is one of the most common JWT-related security bugs in real-world code.

JWT security has a well-documented set of pitfalls that a decoder helps you spot during code review and incident response. The most famous is the 'alg:none' vulnerability , early JWT libraries accepted tokens with the algorithm header set to 'none', which meant any caller could create a token by simply Base64-encoding a payload with no signature. Modern libraries reject 'none' by default, but legacy systems and bespoke implementations occasionally retain the bug. A decoder that surfaces the algorithm makes that vulnerability visible. The second common pitfall is algorithm confusion , accepting a token signed with HS256 (symmetric) when the verifier was configured for RS256 (asymmetric), which lets an attacker use the public key as a signing secret. Watch the alg field carefully when troubleshooting authentication issues across services.

Time-based claims (exp, nbf, iat) are the second most consequential thing to inspect. The 'exp' claim is a Unix timestamp specifying when the token stops being valid; tokens past exp should be rejected by every conformant verifier. The 'nbf' (not before) claim provides the lower bound; the 'iat' (issued at) claim records issuance time. Real-world clock skew between systems is a frequent cause of authentication failures: a token that the issuing server considers freshly minted may be rejected by a verifier whose clock is two minutes behind. Most production verifiers tolerate a few seconds of skew; if you see authentication fail with 'token not yet valid' messages, clock drift is the first thing to check.

Best practices for handling JWTs have tightened considerably since the format's introduction. Tokens should have short lifetimes (typically 5–60 minutes for access tokens), be paired with longer-lived refresh tokens for re-issuance, and be transmitted over HTTPS only. Sensitive information should not be placed in claims because the payload is base64-encoded but not encrypted , anyone with the token can read it. For confidentiality, use JSON Web Encryption (JWE, RFC 7516) instead of plain JWT. For revocation before expiration, maintain a server-side denylist or use opaque tokens backed by a session store. The right primitive depends on your threat model; a decoder lets you confirm which choices the system made.