A JSON Web Token is not a mystery box — it is three segments of base64url-encoded JSON separated by dots. Once you know which segment holds the algorithm, which holds the claims, and which holds the proof, a token stops being opaque and starts being useful. This guide walks through each part with practical details, then points you to our free decoder for quick verification.
The Anatomy: Three Dots Tell Everything
A JWT is literally header.payload.signature. Each part is a base64url-encoded JSON object. There is no encryption hiding the payload by default — only encoding. That means anyone with the token can read the claims; the signature only proves that nobody altered them after they were signed. Understanding that distinction is the first step toward safe token use.
The header is small. It typically names the algorithm (HS256 or RS256) and the token type (JWT). The algorithm matters: HS256 uses a shared secret, while RS256 uses an asymmetric public/private pair. You should prefer RS256 or ES256 in multi-service architectures because a leaked private key cannot forge tokens signed with the public counterpart.
The payload carries claims. Standard claims include iss (issuer), sub (subject or user), aud (intended audience), exp (expiration as Unix epoch seconds), nbf (not before), and iat (issued at). Your auth server may add custom claims such as roles or tenant IDs. Every claim is readable by anyone holding the token, so never place passwords, personal identifiers, or financial details here.
Header Details and Algorithm Safety
The header JSON is typically just two keys: alg and typ. Some tokens add kid (key ID) when multiple signing keys exist. A common vulnerability is an attacker changing alg to none and stripping the signature; some older libraries accepted this. Modern libraries reject none by default, but you should still verify that your parsing code treats the algorithm explicitly rather than trusting whatever the token claims.
If you see alg: HS256, the signature is computed with HMAC using SHA-256 and a shared secret. If you see RS256, the server signs with its private RSA key and verifies with its public key. The choice affects how you rotate keys and how you distribute verification logic across services. In general, asymmetric algorithms scale better and reduce secret-sprawl.
Payload Claims: Reading the Real Story
Claims are the business value of the token. sub tells you which account or user the token represents. aud tells you which service the token is intended for — a common source of 401 errors is a token minted for one audience used against another. iss tells you which authorization server created it, useful when you operate multiple identity providers.
The time trio — iat, nbf, and exp — controls token lifetime. Short-lived access tokens (often 15 minutes or less) limit exposure if a token leaks. Refresh tokens, which are longer-lived, should be stored securely and revoked on logout. Always check exp server-side; never rely only on client-side expiry checks, because the client clock can be wrong or manipulated.
Signature Verification: The Only Trust Boundary
The signature is the only thing that makes a JWT trustworthy. It is not a checksum of the payload alone — it covers both header and payload together. Changing a single character in either segment invalidates the signature. Verification requires the same secret (for HS) or the public key (for RS) that signed it.
Always verify signatures server-side. Client-side libraries that skip verification expose your application to forged tokens. If your service receives tokens from multiple issuers, maintain a mapping of iss to public keys or JWKS endpoints. Key rotation should be planned: publish new keys before retiring old ones, so in-flight tokens do not break during the transition.
Safe Decoding and Common Mistakes
Decoding a JWT is easy: split on dots, base64url-decode each segment, and parse JSON. What matters is what you do afterward. Never execute logic based solely on a decoded payload without verifying the signature. Never store sensitive data in claims. Never trust client-side expiry as authorization.
A practical workflow: paste a token into our JWT Decoder to read claims and check exp. Confirm the header algorithm. Check that aud matches your service. Then verify the signature with your backend key or JWKS endpoint. If any of those steps fails, reject the token regardless of how correct the claims look.
JWT FAQs
Can anyone read a JWT payload?
Yes. The payload is base64url-encoded, not encrypted. Anyone holding the token can decode and read every claim. The signature only prevents tampering; it does not hide content.
Why does my token work in one environment but fail in another?
The most common causes are wrong aud, expired exp, or different signing keys per environment. Decode the failing token and compare its claims to a working one — differences usually reveal the issue in seconds.
Is it safe to paste JWTs into online decoders?
Only if the decoder is trustworthy and runs locally. Avoid sending production tokens to unknown services. Use short-lived test tokens, rotate anything that touches an external site, and prefer decoders that process everything in your browser.
Putting It Together
A JWT is a signed contract, not a secret message. The header names the signing method, the payload states who the token is for and when it expires, and the signature proves integrity. Read the header to know the algorithm, read the payload to understand the user and lifetime, and verify the signature before acting. That sequence turns an opaque string into a reliable authentication mechanism.
Read the claims, check the expiry, verify the signature.
Decode JWT Free