Secure REST APIs with Node.js, Express, and JWT

Introduction

In modern web development, building a REST API that is both flexible and secure is a foundational skill. Whether you are creating a mobile app backend, a single-page application server, or a microservice, the need to authenticate users and protect routes is universal. This article focuses on building secure REST APIs with Node.js, Express, and JWT authentication. We will go beyond a trivial login example and explore a production-grade architecture that includes access tokens, refresh tokens, role-based access control, and security hardening.

Node.js offers an event-driven, non-blocking I/O model that is ideal for scalable APIs. Express remains the most popular web framework for Node.js due to its minimalist design and vast ecosystem. JSON Web Tokens (JWT) provide a stateless mechanism for transmitting claims between parties, making them a natural fit for RESTful services. However, JWTs are often misused, leading to vulnerabilities such as token leakage, weak secret keys, or missing expiration handling.

By the end of this guide, you will understand the core concepts behind JWT-based auth, how to structure an Express application for security, and how to deploy it with confidence. The code examples are written for Node.js 20+ and Express 4.x, following current best practices from official documentation. We assume you have basic familiarity with JavaScript, npm, and RESTful principles. If you are new to Node.js, consult the official Node.js documentation linked in the references.

Throughout the article, we emphasize practical decisions: choosing between symmetric and asymmetric JWT signing, implementing token rotation, and avoiding common pitfalls that compromise security. Secure APIs are not an afterthought; they are designed from the first line of code. The patterns described here apply equally to monoliths and distributed systems.

Table of Contents

• Introduction
• Core Concepts
• Architecture Overview
• Step-by-Step Guide
• Real-World Examples
• Production Code Examples
• Comparison Table
• Best Practices
• Common Mistakes
• Performance Tips
• Security Considerations
• Deployment Notes
• Debugging Tips
• FAQ
• Conclusion

Core Concepts

Before writing code, we must clarify the building blocks of a secure REST API. REST (Representational State Transfer) is an architectural style that uses HTTP verbs and status codes to manipulate resources. A secure REST API ensures that only authenticated and authorized principals can access or mutate resources. Statelessness is a key constraint: each request must contain all information needed to process it.

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact, URL-safe means of representing claims to be transferred between two parties. A JWT consists of three parts separated by dots: a header (specifying algorithm), a payload (claims such as subject and expiration), and a signature (verifying integrity). The signature is produced using a secret (HS256) or a private key (RS256). Because the payload is only base64url-encoded, never trust it without verifying the signature.

Authentication verifies who a user is, typically via credentials. Authorization determines what they can do. In our design, we issue a short-lived access token (e.g., 15 minutes) and a longer-lived refresh token (e.g., 7 days) stored securely in an HttpOnly cookie. This split reduces the blast radius if an access token is stolen. The access token is used for routine API calls; the refresh token is only sent to the token endpoint.

Password hashing is non-negotiable. We use bcrypt or Argon2 to hash passwords with a per-user salt. Never store plaintext passwords. The crypto module in Node.js provides helpers, but dedicated libraries like bcryptjs simplify integration. A password hash should take measurable time (e.g., 10-12 bcrypt rounds) to thwart brute-force attacks.

Role-based access control (RBAC) is implemented by embedding a role claim in the JWT. Middleware checks the role before allowing access to admin routes. This keeps authorization logic centralized and testable. Claims in a JWT can be registered (like sub, exp, iat), public, or private (custom). Avoid placing sensitive data in the payload because it can be decoded by anyone holding the token.

Another concept is statelessness. JWTs allow the API to scale horizontally because any node can validate a token using the shared secret or public key. However, statelessness makes immediate revocation harder; we discuss revocation strategies later using token identifiers (jti) and denylists. Finally, transport security is mandatory. Always serve APIs over TLS (HTTPS). Tokens sent over plain HTTP are trivially intercepted by network attackers.

Architecture Overview

A well-structured Express application separates concerns into layers. The entry point creates the server, loads environment configuration, and mounts routers. Routers delegate to controllers, which use services for business logic. Data access is isolated in repositories or ORM models. Authentication middleware sits between the router and controller to enforce security.

We propose the following high-level flow:

• Client sends credentials to POST /api/auth/login.
• Auth service verifies password hash and generates access + refresh tokens.
• Refresh token is stored in an HttpOnly, Secure, SameSite cookie; access token returned in JSON response (or also cookie depending on SPA).
• Client includes access token in Authorization: Bearer header for protected requests.
• Auth middleware verifies signature, expiration, and role claims.
• On logout, server invalidates refresh token (via denylist or rotating token version).

This design supports both single-page apps and mobile clients. For server-to-server communication, consider client credentials flow or mTLS. The API process itself should remain thin: complex domain logic belongs in services, not in route handlers. Error handling is centralized via an error middleware that returns consistent JSON shapes.

We also integrate cross-cutting middleware: helmet for security headers, cors with strict origins, rate limiter to prevent brute force, and morgan for structured logging in development. A health check route (/healthz) is added for orchestrators. The token verification step occurs early in the middleware chain to reject unauthorized requests before they reach expensive logic.

Step-by-Step Guide

Let us build the project from scratch. Initialize a Node.js project and install dependencies. The following steps assume a Linux or macOS terminal, but commands are cross-platform.

1. Project Setup

Create a directory and run npm init -y. Install express, jsonwebtoken, bcryptjs, dotenv, cookie-parser, helmet, cors, express-rate-limit. For data, we will use an in-memory store for brevity, but in production use PostgreSQL or MongoDB with a connection pool. Create folders: src/controllers, src/middleware, src/services, src/config.

2. Configuration

Create a .env file with JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, ACCESS_TTL, REFRESH_TTL, DATABASE_URL, PORT. Load with dotenv. Never commit secrets to version control; add .env to .gitignore. Use a secret manager in production.

3. User Registration

Implement a controller that validates input, hashes password with bcrypt, and saves user. Return 201 Created with a sanitized user object (no password hash). Validate email format and password length. This prevents malformed data from reaching the database.

4. Login and Token Issuance

Verify credentials, then call token service to sign JWTs. Set refresh cookie with flags. Respond with access token and basic user info. Ensure that invalid credentials return a generic 401 to avoid user enumeration.

5. Protecting Routes

Write authenticateToken middleware that extracts bearer token from Authorization header, verifies with access secret, and attaches req.user. If missing or invalid, return 401/403. Place this middleware before route handlers that need protection.

6. Role Checks

Create requireRole('admin') factory that returns middleware checking req.user.role. This composable pattern allows fine-grained authorization without repeating code.

7. Refresh and Logout

Expose POST /api/auth/refresh that reads cookie, verifies, issues new access token. Logout clears cookie and adds token id to denylist (e.g., Redis). Implement refresh token rotation: issue a new refresh token on each refresh and invalidate the old one.

8. Error Handling

Add a centralized error handler that catches async errors and formats them. Never leak stack traces to clients. Log errors server-side with correlation IDs for debugging.

Real-World Examples

Consider an e-commerce platform where a mobile app communicates with the API. The login flow uses the refresh cookie so the app does not need to store tokens in local storage. Admin staff use a web dashboard that calls the same API with elevated role claims to manage inventory. The token's audience (aud) claim can restrict which services accept it.

Another example is a B2B microservice that exposes read-only metrics. Here, JWTs are signed with RS256; the resource server only needs the public key to verify, enabling decentralized trust. The API gateway validates the token once and forwards user context via headers. This pattern reduces duplicated auth logic across services.

In a social media backend, short-lived access tokens protect user feeds while refresh tokens stored in secure cookies keep sessions alive. When a user changes password, the system can revoke all refresh tokens by bumping a token version stored in the user record, forcing re-login.

Production Code Examples

Below are realistic, technically correct snippets. They use single quotes for JS strings to stay consistent. In production, split files and add tests.

const jwt = require('jsonwebtoken');const crypto = require('crypto');function signAccessToken(user) {  return jwt.sign(    { sub: user.id, role: user.role, type: 'access' },    process.env.JWT_ACCESS_SECRET,    { expiresIn: process.env.ACCESS_TTL || '15m', algorithm: 'HS256' }  );}function signRefreshToken(user) {  return jwt.sign(    { sub: user.id, type: 'refresh', jti: crypto.randomUUID() },    process.env.JWT_REFRESH_SECRET,    { expiresIn: process.env.REFRESH_TTL || '7d', algorithm: 'HS256' }  );}function verifyAccessToken(token) {  return jwt.verify(token, process.env.JWT_ACCESS_SECRET, { algorithms: ['HS256'] });}

The token service above separates signing from business logic. Using jti (JWT ID) enables revocation. The algorithm is explicitly set to prevent algorithm confusion attacks.

const { verifyAccessToken } = require('./tokenService');function authenticateToken(req, res, next) {  const authHeader = req.headers['authorization'];  const token = authHeader && authHeader.split(' ')[1];  if (!token) return res.status(401).json({ error: 'Missing token' });  try {    const payload = verifyAccessToken(token);    req.user = payload;    next();  } catch (err) {    return res.status(403).json({ error: 'Invalid or expired token' });  }}function requireRole(role) {  return (req, res, next) => {    if (req.user?.role !== role) {      return res.status(403).json({ error: 'Insufficient permissions' });    }    next();  };}

The middleware validates the bearer token and attaches the payload. Role checks are composable. Note the optional chaining for safety.

const bcrypt = require('bcryptjs');const { signAccessToken, signRefreshToken } = require('./tokenService');async function login(req, res) {  const { email, password } = req.body;  const user = await userRepo.findByEmail(email);  if (!user) return res.status(401).json({ error: 'Invalid credentials' });  const valid = await bcrypt.compare(password, user.passwordHash);  if (!valid) return res.status(401).json({ error: 'Invalid credentials' });  const accessToken = signAccessToken(user);  const refreshToken = signRefreshToken(user);  res.cookie('refreshToken', refreshToken, {    httpOnly: true,    secure: process.env.NODE_ENV === 'production',    sameSite: 'strict',    maxAge: 7 * 24 * 60 * 60 * 1000  });  res.json({ accessToken, user: { id: user.id, role: user.role } });}

The login controller hashes comparison using bcrypt, then sets a secure cookie. Response omits sensitive fields. In a real app, add rate limiting before this controller.

async function refresh(req, res) {  const token = req.cookies.refreshToken;  if (!token) return res.status(401).json({ error: 'Missing refresh token' });  try {    const payload = jwt.verify(token, process.env.JWT_REFRESH_SECRET);    const user = await userRepo.findById(payload.sub);    if (!user) return res.status(403).json({ error: 'Invalid' });    const accessToken = signAccessToken(user);    res.json({ accessToken });  } catch (e) {    res.status(403).json({ error: 'Invalid refresh token' });  }}

Refresh endpoint validates the cookie and issues a new access token. For rotation, sign a new refresh token and update the stored jti.

Comparison Table

Choosing the right authentication mechanism depends on your constraints. The table below compares session-based auth, JWT, and OAuth2 delegated access.

Best Practices

• Use short-lived access tokens (5-15 minutes) to limit exposure.
• Store refresh tokens in HttpOnly Secure cookies with SameSite attribute.
• Always serve over HTTPS; redirect HTTP to HTTPS at the proxy.
• Validate all input with a schema library like Joi or Zod.
• Use asymmetric signing (RS256) when multiple services verify tokens.
• Rotate signing keys and support key IDs (kid) in JWT header.
• Log authentication events but never log tokens or passwords.
• Apply rate limiting on auth endpoints to prevent brute force.
• Set explicit CORS origins; do not use wildcard with credentials.
• Use environment-specific secrets and audit dependencies regularly.

Common Mistakes

• Putting JWTs in localStorage, exposing them to XSS attacks.
• Using weak or hardcoded secrets (e.g., 'secret').
• Not setting token expiration, allowing eternal access.
• Trusting the payload without verifying signature.
• Returning verbose errors that leak stack traces.
• Missing CORS configuration, allowing any origin.
• Using JWT for sessions without considering revocation.
• Storing sensitive data in JWT payload (it is encoded, not encrypted).

Performance Tips

JWT validation is CPU-light but occurs on every request. Use HS256 for symmetric validation if only one service issues and verifies tokens. If using RS256, cache the public key in memory rather than fetching it per request. Avoid heavy middleware before authentication; place authenticateToken early in the chain. For high-throughput APIs, consider offloading TLS termination to Nginx or a load balancer. Use connection pooling for databases and avoid blocking calls in request handlers. Compress responses with gzip and use HTTP/2 for multiplexing.

Security Considerations

Beyond tokens, harden the Express app. Use helmet to set Content-Security-Policy, X-Frame-Options, and remove X-Powered-By. Configure CORS to allow only your frontend origin. Implement a rate limiter (e.g., express-rate-limit) with a strict window on /api/auth/login. Protect against brute force by adding exponential backoff or CAPTCHA after repeated failures.

Secrets must be managed via environment variables or a vault (AWS Secrets Manager, HashiCorp Vault). Never expose JWT secrets in client code. If using RS256, keep the private key in a restricted file or KMS. Monitor for anomalous token usage using logging and alerting. Sanitize all user input to prevent NoSQL injection or SQL injection. Use parameterized queries. Regularly update dependencies to patch known vulnerabilities.

Deployment Notes

For production, run the app behind a reverse proxy (Nginx) with TLS. Use process managers like PM2 or container orchestration (Kubernetes). Set NODE_ENV=production. Provide health check endpoints. Use Docker to package dependencies; see our internal guide on Dockerizing Node.js applications. Ensure environment variables are injected securely. Enable automatic restarts and zero-downtime deployments. Configure horizontal pod autoscaling based on CPU or request rate. Store refresh token denylists in Redis with TTL matching token lifetime.

Debugging Tips

When tokens fail, decode them with the official JWT debugger or jwt.decode() (without verification) to inspect claims. Check server clock skew if using short TTLs. Use Postman to send Authorization headers. Add structured logging in middleware to record token ID and user ID for traceability. If using cookies, verify SameSite and Secure attributes with browser devtools. Enable verbose logging in development only. Write unit tests for token signing and middleware to catch regressions.

FAQ

What is a JWT and why use it?

A JSON Web Token is a signed, compact token that carries claims. It enables stateless authentication, allowing APIs to scale without server-side sessions. The signature ensures the token hasn't been tampered with. It is widely supported across languages and integrates easily with mobile and SPA clients.

How do I expire a JWT?

Set the exp claim when signing (via expiresIn). The verification library automatically rejects expired tokens. For early revocation, maintain a denylist of jti values in Redis. Short TTLs reduce the need for active revocation.

Should I store JWT in localStorage or cookie?

Prefer HttpOnly cookies for refresh tokens to mitigate XSS. Access tokens can be kept in memory or short-lived cookies. localStorage is vulnerable to JavaScript theft because any script on the page can read it.

What is the difference between access and refresh tokens?

Access tokens are short-lived and grant access to resources. Refresh tokens are longer-lived and used only to obtain new access tokens, stored securely. This separation limits damage if an access token leaks.

How do I implement role-based access?

Include a role claim in the JWT payload. Middleware checks req.user.role against required roles before handling the request. You can also use scopes for finer-grained permission sets.

Can JWT be revoked?

Stateless JWTs cannot be revoked easily. Use short TTLs and a server-side denylist for critical revocation, or adopt refresh token rotation. For immediate logout, clear the refresh cookie and invalidate its jti.

Is JWT secure over HTTP?

No. Always use HTTPS. Tokens over plain text can be intercepted by network attackers. TLS also protects against man-in-the-middle modifications.

When should I use OAuth2 instead of JWT?

Use OAuth2 when delegating access to third-party applications or using social logins. JWT is a token format; OAuth2 is a framework that can issue JWTs. For first-party apps, direct JWT issuance is simpler.

How do I handle token theft?

Rotate refresh tokens on each use, detect reuse, and revoke the whole family. Monitor logs for impossible travel or strange user agents. Force password reset if compromise is suspected.

Conclusion

Building secure REST APIs with Node.js, Express, and JWT is achievable with disciplined architecture and adherence to best practices. We covered core concepts, a layered architecture, step-by-step implementation, production code, and operational concerns. Start applying these patterns in your next project, and explore our related articles on Dockerizing Node.js and building microservices with NestJS to deepen your backend expertise. Secure your endpoints today and make authentication a first-class citizen of your design.