JWT Tokens: What You Need to Know

JSON Web Tokens (JWT) have become the standard for modern web authentication. If you're building APIs or microservices, understanding JWTs is critical.

What is a JWT?

A JWT is a compact, URL-safe means of representing claims to be transferred between two parties. It consists of three parts separated by dots:

header.payload.signature

Header

Contains metadata about the token type and hashing algorithm:

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

Payload

Contains the claims (user data):

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Signature

Ensures the token hasn't been tampered with:

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

How JWT Authentication Works

Flow

1. User Login - User provides credentials (username + password)
2. Token Generation - Server verifies credentials and creates JWT
3. Token Storage - Client stores JWT (localStorage, sessionStorage)
4. Token Transmission - Client sends JWT with each request
5. Token Verification - Server validates signature and claims
6. Access Granted - If valid, access is granted

JWT Structure Example

Real JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoded:

• Header: {"alg":"HS256","typ":"JWT"}
• Payload: {"sub":"1234567890","name":"John Doe","iat":1516239022}
• Signature: (cryptographic signature)

Common JWT Claims

Reserved Claims

• iss (Issuer) - Who created the token
• sub (Subject) - Who the token is for
• aud (Audience) - Who can use the token
• exp (Expiration Time) - When token expires
• iat (Issued At) - When token was created
• nbf (Not Before) - When token becomes valid

Custom Claims

Add any custom data your application needs:

{
  "user_id": 123,
  "username": "john_doe",
  "roles": ["admin", "editor"],
  "permissions": ["read", "write"]
}

Security Best Practices

1. Use Strong Secrets

// Bad
const secret = "secret";

// Good
const secret = crypto.randomBytes(32).toString('hex');

2. Set Expiration Times

{
  "exp": Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour
}

3. Use HTTPS Always

Never transmit JWTs over unencrypted connections.

4. Store Securely

// Good: HttpOnly cookie
response.cookie('token', jwt, {
  httpOnly: true,    // Can't be accessed by JavaScript
  secure: true,      // HTTPS only
  sameSite: 'strict' // CSRF protection
});

// Acceptable: sessionStorage (not localStorage)
sessionStorage.setItem('token', jwt);

5. Validate on Every Request

function verifyToken(token, secret) {
  try {
    return jwt.verify(token, secret);
  } catch (err) {
    return null;
  }
}

6. Use Algorithm Whitelisting

const decoded = jwt.verify(token, secret, {
  algorithms: ['HS256'] // Only allow specific algorithms
});

Common Pitfalls

❌ Mistake 1: Storing Sensitive Data in JWT

JWTs are encoded, not encrypted. Anyone can decode them:

// Bad - Anyone can read this
{
  "password": "secret123",
  "api_key": "sk-1234567890"
}

// Good - Store only non-sensitive identifiers
{
  "user_id": 123,
  "email": "user@example.com"
}

❌ Mistake 2: Not Validating Expiration

Always check the exp claim:

const decoded = jwt.verify(token, secret);
// verify() already checks exp, but make sure you're using it

❌ Mistake 3: Weak Algorithms

// Bad
{
  "alg": "none"  // No signature verification!
}

// Good
{
  "alg": "HS256" // or RS256, ES256, etc.
}

JWT Use Cases

✓ Stateless Authentication

Perfect for API authentication - no session storage needed.

✓ Single Sign-On (SSO)

Share authentication across multiple services.

✓ Mobile Applications

Avoid session management overhead.

✓ Third-party API Authorization

Grant limited access without sharing passwords.

When NOT to Use JWT

✗ Logout Functionality

JWTs are hard to revoke. You still need a blacklist for logout.

✗ Highly Sensitive Operations

For critical operations, use server-side session validation.

✗ Very Short-lived Sessions

The overhead isn't worth it.

Decoding and Testing JWTs

Use our JWT Decoder tool to:

• ✓ Decode and inspect JWT payloads
• ✓ Verify signatures
• ✓ Check claims and expiration
• ✓ Debug authentication issues

Tools & Resources

• JWT.io Debug Tool
• IANA JWT Registry
• RFC 7519: JSON Web Token

Summary

JWTs are a powerful authentication mechanism:

• ✓ Stateless - No server-side storage needed
• ✓ Scalable - Perfect for microservices
• ✓ Secure - Cryptographically signed
• ⚠️ Be careful - Never store sensitive data, always validate

Start exploring JWTs with our JWT Decoder tool now.