What Is JWT? Structure, Signing & Safe Use

Three base64url chunks separated by dots β€” a header, a payload and a signature. Learn what each part proves, what it does not prove, and the five mistakes that turn a JWT into a security hole.

πŸ“‚ Developer Essentials ⏱ About 11 minutes πŸ“Ά Intermediate πŸ› οΈ Pairs with: JWT Decoder

What you will learn

  • Read a JWT and name its three parts
  • Explain what the signature proves β€” and what it doesn't
  • Use the standard claims (exp, iss, aud, sub) correctly
  • Decide when a JWT beats a server-side session (and when it loses)
  • Avoid the five classic JWT security mistakes
In this guide
  1. What a JWT is
  2. Anatomy: the three parts
  3. How signing and verification work
  4. The standard claims
  5. When to use a JWT β€” and when not to
  6. Common mistakes
  7. Try it: JWT Decoder
  8. Frequently asked questions

What a JWT is

A JSON Web Token (JWT) is a compact, URL-safe way to pass a signed claim between two parties. It looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlZhbGV2IiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Three blocks, separated by dots: header.payload.signature. A server creates one after you log in, hands it to you, and you send it back with every request β€” usually in an Authorization: Bearer <token> header. The server verifies the signature and trusts the claims inside, without looking anything up in a database. That β€œno lookup” property is the whole point β€” and, as we'll see, also the main weakness.

Anatomy: the three parts

Each part is base64url-encoded JSON (base64 with +// replaced by -/_ and padding removed, so it survives in a URL). Decode the example above and you get:

// Header β€” how the token is signed
{ "alg": "HS256", "typ": "JWT" }

// Payload β€” the claims (statements about the user)
{ "sub": "1234567890", "name": "Valev", "admin": true, "iat": 1516239022 }

// Signature β€” HMAC-SHA256 over header.payload, with a secret key
PartContentsSecret?
HeaderSigning algorithm (alg) and type (typ)No β€” readable by anyone
PayloadClaims: who you are, what you may do, when it expiresNo β€” readable by anyone
SignatureHash of header + payload, keyed with a secretYes β€” only the issuer can make it
The payload is encoded, not encrypted. Anyone who gets the token can decode it and read every claim β€” your user ID, your email, your admin flag. Never put passwords, secrets or sensitive personal data in a JWT. If the payload must be secret, you need JWE (encrypted JWT), not a plain JWT.

How signing and verification work

To create the signature, the issuer takes base64url(header) + "." + base64url(payload) and signs it:

HMAC-SHA256(secret, header + "." + payload)   // HS256: shared secret
RS256: sign with a private key, verify with a public key

Verification is the same computation in reverse: the server recomputes the signature over the header and payload it received, using its own secret key, and compares. If even one character of the payload was changed β€” say, flipping "admin": false to true β€” the signature no longer matches and the token is rejected.

Two algorithm families matter. Symmetric (HS256): one shared secret signs and verifies β€” simple, but anyone with the secret can forge tokens, so only the issuer may hold it. Asymmetric (RS256/ES256): a private key signs, a public key verifies β€” the verifier can be a different service, which is how β€œlogin with Google” style federation works.

The standard claims

ClaimMeaningWhy it matters
issIssuer β€” who created the tokenReject tokens from strangers
subSubject β€” whose token this is (user ID)The identity the app acts on
audAudience β€” which service the token is forStops a token for one app being reused in another
expExpiry β€” Unix time after which it is invalidLimits the damage of a stolen token
iatIssued atDetect tokens made before a password change
nbfNot beforeTokens that only become valid later

On top of these, applications add their own claims β€” roles, permissions, a display name. Keep the payload small: the token is sent with every request, so a 5 KB token is a tax on every single call.

When to use a JWT β€” and when not to

JWTs shine when verification must happen without a database round-trip, or across services that don't share a session store: APIs, microservices, and single sign-on. The verifier needs only the key.

They lose in one important way: you cannot easily revoke one. A server-side session can be deleted the moment a user logs out or changes a password; a JWT stays valid until it expires, because there is nothing to delete. The standard mitigations are short expiry times (minutes, not days) plus refresh tokens β€” a long-lived token that is only ever sent to the login endpoint to mint fresh short-lived JWTs β€” or a revocation list, which quietly reintroduces the database lookup the JWT was meant to avoid.

Rule of thumb: if you have one app and one database, a classic session cookie is simpler and safer. Reach for JWT when you have many services, or when the token must cross a trust boundary.

Common mistakes

  • Trusting a client-decoded token. Decoding proves nothing β€” only signature verification does. The admin: true in a decoded payload is a claim, not a fact, until the signature checks out.
  • Accepting alg: none. An unsigned token must be rejected. Libraries that still accept it are the oldest JWT vulnerability in the book β€” and it still shows up.
  • Weak or leaked secrets. HS256 with the secret secret is forgeable in seconds. Use a long random secret, rotate it, and never commit it.
  • No expiry (exp). A stolen token then works forever. Set a short exp and use refresh tokens.
  • Putting secrets in the payload. Base64url is not encryption β€” anyone can read it. See the callout above.
  • Storing tokens in localStorage. Any cross-site scripting (XSS) hole lets an attacker read it. HttpOnly cookies are the safer home for browser tokens.

Try it: JWT Decoder

Paste a token into the JWT Decoder and watch it split into header, payload and human-readable dates β€” the fastest way to see the structure this guide describes.

Open the JWT Decoder β†’

Keep learning

Frequently asked questions

Is a JWT encrypted?

No. A standard JWT (JWS) is signed, not encrypted β€” the payload is base64url, which anyone can decode. Encryption is a separate format, JWE, used when the contents themselves must stay secret.

How do I revoke a JWT when a user logs out?

You can't delete it directly β€” it stays valid until exp. The practical answers are short expiry with refresh tokens, or a server-side denylist of revoked token IDs (the jti claim) checked on sensitive endpoints.

JWT vs session cookie β€” which should I choose?

A session cookie for a single app with a database: simpler, instantly revocable. A JWT for APIs and microservices where verifiers can't share a session store, or where tokens cross service boundaries. Many systems use both: a session for the browser, JWTs for service-to-service calls.

Where should I store a JWT in the browser?

In an HttpOnly, Secure, SameSite cookie β€” JavaScript can't read it, so XSS can't steal it. localStorage is convenient but readable by any script on the page, including an injected one.

Can I decode a JWT without the secret?

Yes β€” decoding the header and payload needs no key at all; only verifying the signature does. That is why the JWT Decoder tool can show you a token's contents instantly, and why you must never put secrets in the payload.