Understanding JWT Tokens: A Developer's Complete Guide

JWTs are everywhere — authentication, API authorization, single sign-on. Yet most developers use them without truly understanding how they work. Let's fix that.

What is a JWT?

A JSON Web Token (JWT) is a compact, URL-safe string that represents claims between two parties. It's pronounced "jot" and looks like this:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.signature

Three parts separated by dots: Header, Payload, Signature.

The Three Parts

1. Header

The header specifies the token type and signing algorithm:

{
  "alg": "HS256",
  "typ": "JWT"
}

This is Base64URL-encoded to form the first part of the token.

2. Payload

The payload contains claims — statements about the user and metadata:

{
  "sub": "1234567890",
  "name": "Jane Doe",
  "iat": 1716239022,
  "exp": 1716242622,
  "role": "admin"
}

Standard claims:

• iss — Issuer (who created the token)
• sub — Subject (who the token is about)
• aud — Audience (who the token is for)
• exp — Expiration time
• iat — Issued at
• nbf — Not valid before
• jti — Unique token ID

3. Signature

The signature ensures the token hasn't been tampered with:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

How Authentication Works with JWT

1. User logs in with email/password
2. Server verifies credentials
3. Server creates a JWT with user info + signs it
4. Server sends JWT to client
5. Client stores JWT (localStorage, cookie, memory)
6. Client sends JWT in Authorization header on each request
7. Server verifies signature + checks expiration
8. Server processes the request

Common Security Mistakes

Never store secrets in the payload

The payload is just Base64-encoded — anyone can decode it:

// This is NOT encryption
atob('eyJwYXNzd29yZCI6InNlY3JldCJ9')
// '{"password":"secret"}'

Always validate the signature server-side

Never trust a JWT without verifying its signature. The whole point of the signature is proving the token was issued by your server.

Set short expiration times

JWTs can't be revoked once issued (unlike session tokens). Keep expiration times short (15 minutes to 1 hour) and use refresh tokens for longer sessions.

Don't use alg: "none"

Some JWT libraries accept alg: "none" which means no signature verification. Always reject tokens with no algorithm.

JWT vs Session Tokens

Debugging JWTs

When a JWT isn't working, you need to inspect its contents. Use our JWT Decoder to:

• See the header algorithm
• Read all payload claims
• Check if the token is expired
• View the issued/expiration timeline

All decoding happens in your browser — your tokens never leave your device.

Key Takeaways

1. JWTs are signed, not encrypted — anyone can read the payload
2. The signature prevents tampering, not reading
3. Keep expiration times short
4. Store tokens securely (httpOnly cookies > localStorage)
5. Always verify signatures server-side