JWT Tokens Decoded: A Developer's Complete Guide
Understand JWT structure, claims, expiration, and security — plus how to decode and debug tokens instantly.
JSON Web Tokens (JWTs) are the backbone of modern authentication. They're used in OAuth 2.0 flows, API authentication, single sign-on (SSO), and session management across virtually every web framework. Understanding their structure is essential for any developer working with authentication systems.
A JWT consists of three Base64URL-encoded parts separated by dots: header.payload.signature. The header declares the token type and signing algorithm. The payload contains claims — data statements about the user and token metadata. The signature verifies the token hasn't been tampered with.
The header typically contains two fields: 'alg' (the signing algorithm like HS256, RS256, or ES256) and 'typ' (always 'JWT'). Some tokens include a 'kid' (Key ID) field that tells the server which key to use for verification — critical in key rotation scenarios.
The payload carries registered claims like 'iss' (issuer), 'sub' (subject — usually the user ID), 'aud' (audience), 'exp' (expiration timestamp), 'iat' (issued at), and 'nbf' (not before). Custom claims are added for application-specific data: user roles, permissions, tenant IDs, email addresses, and more.
Expiration handling is crucial. The 'exp' claim is a Unix timestamp (seconds since epoch). Servers must reject tokens where the current time exceeds 'exp'. Short-lived access tokens (5-15 minutes) combined with longer-lived refresh tokens is the security best practice. Our JWT Decoder displays expiration status in real-time, showing exactly when a token expires or how long ago it expired.
A common debugging scenario: your API returns 401 Unauthorized, and you need to quickly check if the token is expired, issued for the wrong audience, or missing required claims. Paste the token into our decoder and see every claim instantly — no need to write code or use command-line tools.
Security considerations: JWTs are not encrypted by default — they're only signed. Anyone with the token can read the payload by Base64-decoding it. Never put sensitive data like passwords, credit card numbers, or private keys in JWT claims. The signature prevents tampering but does not prevent reading.
Our JWT Decoder runs entirely in your browser. Your tokens — which contain user IDs, permissions, and potentially sensitive claims — are never sent to any server. This is critically important because JWTs are bearer tokens: anyone who has the token can authenticate as that user. Decoding tokens on a third-party website creates a real security risk. Local decoding eliminates it.
For token validation in production, always verify the signature server-side using your secret key or public key. Our decoder inspects structure and claims but intentionally does not verify signatures, since that would require your secret key — which should never leave your server.