JWT Tutorial: What is a JSON Web Token and How Does It Work?

What is a JWT?

JWT stands for JSON Web Token. It is an open standard (RFC 7519) that defines a compact, self-contained way to securely transmit information between parties as a JSON object.

A JWT looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNzQwOTg3MjAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Three parts separated by dots (.): Header . Payload . Signature

JWT Structure: Header, Payload, Signature

1. Header

The header specifies the token type and signing algorithm. It is Base64URL encoded.

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

alg is the algorithm: HS256 (HMAC-SHA256), RS256 (RSA), ES256 (ECDSA). typ is always JWT.

2. Payload (Claims)

The payload contains the claims — statements about the user and additional metadata. Also Base64URL encoded.

{
  "sub": "1234567890",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin",
  "iat": 1740987200,
  "exp": 1741073600
}

Standard claims: sub (subject/user ID), iat (issued at), exp (expiration), iss (issuer), aud (audience).

Important: The payload is only encoded, not encrypted. Anyone can read it. Never put passwords or sensitive data in a JWT payload.

3. Signature

The signature verifies the token has not been tampered with. It is computed as:

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

Only parties that know the secret (or the private key for RS256) can create valid tokens. Anyone can verify the signature using the public key.

How JWT Authentication Works

1. User logs in with username and password
2. Server validates credentials, creates a JWT signed with a secret/private key
3. Server sends the JWT to the client
4. Client stores the JWT (ideally in an httpOnly cookie)
5. Client sends the JWT in the Authorization: Bearer <token> header on every request
6. Server verifies the signature and reads the claims — no database lookup needed
7. If the token is expired or the signature is invalid, the request is rejected

How to Decode a JWT

Since the header and payload are Base64URL encoded (not encrypted), you can decode them without the secret:

In JavaScript:

function decodeJWT(token) {
  const [header, payload] = token.split('.');
  const decode = str => JSON.parse(atob(str.replace(/-/g, '+').replace(/_/g, '/')));
  return {
    header: decode(header),
    payload: decode(payload)
  };
}

const decoded = decodeJWT('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
console.log(decoded.payload.name); // "Alice"

Or use the free JWT Decoder tool — paste your token and instantly see the decoded header, payload, claims, and expiry time.

JWT Signing Algorithms

Common JWT Security Mistakes

• Storing JWT in localStorage - Vulnerable to XSS attacks. Use httpOnly, Secure cookies instead.
• Not checking expiration - Always validate the exp claim server-side. A decoded token does not mean it is valid.
• Using weak secrets - HS256 secrets should be at least 256 bits (32 random bytes). Never use dictionary words.
• Accepting the "none" algorithm - Some old libraries accepted alg: "none" which bypasses signature verification. Always whitelist allowed algorithms.
• Storing sensitive data in payload - Payload is readable by anyone with the token. Only store non-sensitive claims like user ID and roles.
• No token revocation strategy - JWTs cannot be invalidated before expiry. Use short expiration times (15 minutes) and refresh tokens for revocability.

Frequently Asked Questions

What is the difference between JWT and OAuth?

OAuth is an authorization framework that defines how applications can obtain limited access to user accounts. JWT is a token format. OAuth commonly uses JWTs as its access tokens, but OAuth can also use opaque tokens. They are complementary, not competing.

How long should a JWT be valid?

Access tokens should expire in 15 minutes to 1 hour. Use refresh tokens (longer-lived, stored in httpOnly cookies) to silently issue new access tokens. Short expiry limits the damage if a token is stolen.

Can I use JWT without HTTPS?

No. JWT tokens must be transmitted over HTTPS. Over plain HTTP, tokens can be intercepted by a man-in-the-middle attack. Always use TLS in production.

Where can I decode a JWT for debugging?

Use the JWT Decoder at JSON Web Tools. Unlike jwt.io, your token is decoded entirely in your browser and never sent to any server, making it safe to use with real tokens during debugging.