JWT Explained for Beginners
3 min read · Published
Table of contents
A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe string that carries claims about a user or client, and is signed so the receiver can detect tampering. JWTs are widely used for API authentication and for passing identity between services (OpenID Connect ID tokens are JWTs).
What a JWT looks like
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJBZGEiLCJleHAiOjE3MDAwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Three Base64URL-encoded parts separated by dots: header.payload.signature. Paste any token into the JWT Decoder to see the parts without sending them anywhere.
The three parts
Header
Describes the token and the signing algorithm:
{ "alg": "HS256", "typ": "JWT" }
Payload (claims)
The data. Some claims are registered by the standard:
| Claim | Meaning |
|---|---|
iss |
Issuer: who created the token |
sub |
Subject: who it is about (usually a user ID) |
aud |
Audience: who the token is intended for |
exp |
Expiration time (Unix seconds) |
nbf |
Not valid before (Unix seconds) |
iat |
Issued at (Unix seconds) |
jti |
Unique token ID |
{ "sub": "12345", "name": "Ada", "role": "admin", "iat": 1699990000, "exp": 1700000000 }
The time claims are Unix timestamps in seconds; convert them with the Timestamp Converter or read Understanding Unix Timestamps.
Signature
The issuer computes a signature over base64url(header) + "." + base64url(payload). With HS256 this is an HMAC-SHA-256 using a shared secret; with RS256 or ES256 it is a digital signature made with a private key and checked with a public key. If anyone changes a single character of the header or payload, verification fails.
Encoded does not mean encrypted
This is the most important thing to understand. The header and payload are only Base64URL encoded (see Base64 Encoding Explained). Anyone who has the token can read them. Never put passwords, card numbers or other secrets in a JWT payload.
Decoding is not verifying
Decoding reveals the claims. Verifying checks the signature with the right key and also validates exp, nbf, iss and aud. A tool that only decodes, including ours, cannot tell you whether a token is genuine. Your server must verify every token it accepts.
How a typical login flow works
- The client sends credentials to the login endpoint.
- The server checks them and returns a signed JWT (the access token) with a short
exp, often 5 to 60 minutes. - The client sends it on later requests:
Authorization: Bearer <token>. - The server verifies the signature and claims, then handles the request.
- When the token expires, the client uses a refresh token to obtain a new one.
Common mistakes and security pitfalls
- Accepting
alg: none. Always require an explicit allow-list of algorithms on the server. - Algorithm confusion. Do not let the token's header decide whether to treat a public key as an HMAC secret.
- Weak HMAC secrets. Use at least 256 bits of random data, such as one from the Password Generator.
- Long-lived tokens. A JWT cannot be revoked by itself; keep
expshort and rotate refresh tokens. - Storing tokens carelessly.
localStorageis readable by any script on the page (XSS). HttpOnly, Secure, SameSite cookies are safer against theft but need CSRF protection. - Skipping
audandisschecks. A token issued for service A should not be accepted by service B.
When not to use JWTs
For a simple server-rendered site, a random session ID stored server-side is simpler, revocable and smaller. JWTs shine when several independent services must trust a token without calling a central session store.
Debugging tips
If a request fails with 401, decode the token and check: Is exp in the past? Is nbf in the future? Is aud correct? Does the clock on your server drift from the issuer? Our decoder shows the status immediately. For status-code semantics see Common HTTP Status Codes.
Related tools
JWT Decoder
Decode JWT header, payload and expiry. Never leaves your browser.
Base64 Encoder/Decoder
Encode text to Base64 or decode it back, with full Unicode support.
Timestamp Converter
Convert Unix timestamps to dates and back, in UTC and local time.
FAQ
Is a JWT encrypted?
A standard signed JWT (JWS) is only encoded and signed, not encrypted. Anyone holding the token can read its payload.
Where should I store a JWT in a browser?
There is no perfect answer. HttpOnly, Secure, SameSite cookies protect against script theft; localStorage is exposed to XSS. Choose based on your threat model.
Why do JWTs expire?
Because a signed token cannot be revoked by itself. A short exp limits the damage if one leaks.
Keep reading
- Base64 Encoding Explained
How Base64 works, why it exists, how much it inflates data, URL-safe Base64, Unicode pitfalls and when not to use it.
- Understanding Unix Timestamps
What Unix time is, seconds vs milliseconds, time zones, the Year 2038 problem and how to convert timestamps in JavaScript, Python and SQL.