Understanding JWT Tokens

JWT tokens look intimidating — that long string with two dots, like someone mashed their keyboard and called it authentication. But once you decode one, you realize it's just JSON wearing a trenchcoat. I remember the first time I cracked one open in a debugger and thought "wait, that's it?" Three Base64 chunks, a bit of crypto, and suddenly you've got stateless auth. In this guide I'll break down exactly how they work, because once you see the internals, JWTs stop being scary and start being one of the most useful tools in your stack.

What Is a JWT?

A JSON Web Token is a compact, URL-safe token format defined in RFC 7519. It is used to securely transmit information between parties as a JSON object. The information can be verified and trusted because it is digitally signed — either using a secret (HMAC) or a public/private key pair (RSA or ECDSA).

JWTs are commonly used for:

• Authentication: After login, a JWT is issued and sent with subsequent requests to identify the user.
• Authorization: JWTs can carry permission claims that determine what resources a user can access.
• Information exchange: JWTs can securely transmit data between services in a microservices architecture.

JWT Structure: Three Parts

A JWT consists of three Base64URL-encoded parts separated by dots:

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

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

Standard JWT Claims

JWT Security Best Practices

JWT in Practice: Authentication Flows

Understanding JWT structure is one thing — knowing how to use JWTs correctly in a real authentication system is another. This section covers the complete OAuth 2.0 + JWT flow, refresh token strategies, practical Node.js implementation, and how to handle the inherent statelessness of JWTs.

The Complete OAuth 2.0 + JWT Flow

In a typical OAuth 2.0 authorization code flow with JWTs, the sequence works as follows:

1. The user clicks "Login" and is redirected to the authorization server (e.g., Auth0, Okta, or your own).
2. The user authenticates and grants permission. The authorization server redirects back with an authorization code.
3. Your server exchanges the code for an access token (JWT) and a refresh token via a back-channel request.
4. The access token is sent with each API request in the Authorization: Bearer <token> header.
5. Your API validates the JWT signature and claims on every request — no database lookup needed.
6. When the access token expires, the client uses the refresh token to obtain a new access token.

Refresh Token Rotation

Refresh tokens are long-lived credentials that can obtain new access tokens. Because they are valuable, they need careful handling. Refresh token rotation is a security strategy where each time a refresh token is used, it is invalidated and a new one is issued. This limits the damage if a refresh token is stolen — the attacker can only use it once before it becomes invalid.

Implement refresh token rotation by storing refresh tokens in your database with a one-time-use flag. When a refresh token is presented, mark it as used and issue a new pair. If you detect a refresh token being used twice (a sign of theft), invalidate the entire token family for that user and force re-authentication.

Implementing JWT in Node.js

The jsonwebtoken library is the standard choice for JWT operations in Node.js:

const jwt = require("jsonwebtoken")

const SECRET = process.env.JWT_SECRET // min 256-bit random string

// Sign a token (on login)
const token = jwt.sign(
  { sub: user.id, email: user.email, role: user.role },
  SECRET,
  { expiresIn: "15m", issuer: "https://api.example.com" }
)

// Verify a token (on each request)
try {
  const payload = jwt.verify(token, SECRET, {
    issuer: "https://api.example.com",
    algorithms: ["HS256"] // explicitly specify algorithm
  })
  // payload.sub, payload.email, payload.role are now available
} catch (err) {
  if (err.name === "TokenExpiredError") {
    // Prompt client to refresh
  } else {
    // Invalid token — reject request
  }
}

Common JWT Vulnerabilities

Revoking JWTs Without a Blacklist

JWTs are stateless by design — the server does not store them, so there is no built-in way to revoke a specific token before it expires. The common approaches to handle revocation are:

• Short expiration times: Use 15-minute access tokens. A stolen token becomes useless quickly.
• Token version in the payload: Store a tokenVersion counter in your user database. Include it in the JWT. On logout or password change, increment the counter. Reject tokens with an outdated version.
• Redis-based denylist: For immediate revocation, maintain a small Redis set of revoked JTI (JWT ID) values. Check this set on each request. The set only needs to hold tokens until they expire naturally.

Decode a JWT Token

Use our free JWT decoder to inspect the header, payload, and claims of any JWT token:

JWT Security Best Practices: A Comprehensive Guide

Security is not optional when working with JWTs. A misconfigured JWT implementation can give attackers full access to your system. This section consolidates every security consideration into a single actionable reference that covers validation, storage, expiration, revocation, and defense against known attacks.

Always Validate the Signature

The most critical rule: never trust a JWT payload without verifying its signature first. Decoding a JWT (Base64 decoding the payload) only reads the data — it does not confirm that the token is authentic. An attacker can craft any payload they want. Only signature verification proves the token was issued by your server and has not been tampered with.

// ❌ WRONG — only decodes, does NOT verify
const payload = JSON.parse(atob(token.split(".")[1]))

// ✅ CORRECT — verifies signature before trusting payload
const payload = jwt.verify(token, SECRET, {
  algorithms: ["HS256"],  // explicitly whitelist algorithms
  issuer: "https://api.example.com",
  audience: "https://app.example.com"
})

Never Trust the Payload Without Verification

Even after signature verification, you must validate the claims inside the token. Check that the exp claim has not passed, that iss matches your expected issuer, and that aud matches your application. A valid signature only means the token was issued by someone with the key — it does not mean the token is still valid or intended for your service.

Use Short Expiration Times

Access tokens should expire quickly — typically 15 minutes for high-security applications and no more than 1 hour for standard applications. Short-lived tokens limit the damage window if a token is stolen. An attacker who captures a token can only use it until it expires. Combine short expiration with refresh token rotation for the best balance of security and user experience.

Implement Token Refresh Flows

Refresh tokens are long-lived credentials (days or weeks) stored securely on the server side. When an access token expires, the client presents the refresh token to obtain a new access token without requiring the user to log in again. Always implement refresh token rotation — each time a refresh token is used, invalidate it and issue a new one. If a refresh token is used twice, it indicates theft, and you should revoke the entire token family.

// Refresh token endpoint
app.post("/auth/refresh", async (req, res) => {
  const { refreshToken } = req.body
  
  // Check if refresh token exists and is unused
  const stored = await db.findRefreshToken(refreshToken)
  if (!stored || stored.used) {
    // Token reuse detected — revoke entire family
    await db.revokeTokenFamily(stored.familyId)
    return res.status(401).json({ error: "Token reuse detected" })
  }
  
  // Mark current refresh token as used
  await db.markAsUsed(refreshToken)
  
  // Issue new token pair
  const newAccessToken = jwt.sign({ sub: stored.userId }, SECRET, { expiresIn: "15m" })
  const newRefreshToken = crypto.randomUUID()
  await db.storeRefreshToken(newRefreshToken, stored.userId, stored.familyId)
  
  res.json({ accessToken: newAccessToken, refreshToken: newRefreshToken })
})

Store Tokens Securely: httpOnly Cookies vs localStorage

Where you store JWTs in the browser has significant security implications. localStorage is accessible to any JavaScript running on the page, making it vulnerable to XSS (Cross-Site Scripting) attacks. A single XSS vulnerability allows an attacker to steal all tokens from localStorage. httpOnly cookies, on the other hand, cannot be accessed by JavaScript at all — they are only sent automatically with HTTP requests.

Revocation Strategies

JWTs are stateless by design, which means there is no built-in way to revoke them before expiration. However, you have several options depending on your security requirements:

• Short expiration + refresh rotation: The simplest approach. Tokens expire quickly, and refresh tokens can be revoked server-side.
• Token version (per-user): Store a version counter in your user record. Include it in the JWT. On logout or password change, increment the version. Reject tokens with an old version.
• JTI denylist in Redis: Store revoked token IDs (jti claim) in Redis with a TTL matching the token's remaining lifetime. Check the denylist on each request.
• Event-driven invalidation: Publish a revocation event when a user logs out. All services subscribe and add the JTI to their local denylist cache.

Common JWT Attacks

Understanding how attackers exploit JWTs helps you defend against them:

JWT Implementation Checklist (Production-Ready)

After implementing JWT auth in dozens of projects, here's the checklist I follow every time. Miss any of these and you'll have a security audit finding:

JWT vs Alternatives: When NOT to Use JWT

JWT is fantastic for many use cases, but it's not always the right choice. Here's when you should consider alternatives:

The most common mistake I see: teams use JWT for everything because they heard "JWTs are scalable" without understanding the trade-offs. If you need instant logout, frequent permission changes, or real-time revocation — server-side sessions are often simpler and more secure.