express-jwt

8.5.1 verified Sat Apr 25 auth: no javascript

Express middleware for validating JWTs (JSON Web Tokens) via the jsonwebtoken library. As of v8.5.1, it supports async secret retrieval, token revocation checks, and a customizable request property (default `req.auth`). It is fully typed (TypeScript) and ESM/CJS compatible. Key differentiators: built-in `.unless()` for path exclusion, optional `credentialsRequired` for public endpoints, and all jsonwebtoken verify options (audience, issuer, clockTolerance, etc.). However, v7→v8 introduced several breaking changes: the exported function is now `expressjwt` (not `jwt`), the request property changed from `req.user` to `req.auth`, and `algorithms` is now required to prevent downgrade attacks. The package is maintained by Auth0 with quarterly releases.

Common errors

error TypeError: jwt is not a function ↓

cause Using default import on v8+ where only named export `expressjwt` exists.

fix

Change import to import { expressjwt as jwt } from 'express-jwt'

error Error: secret must be a string or buffer ↓

cause Providing an undefined or invalid `secret` option to expressjwt.

fix

Ensure secret is a non-empty string or Buffer, e.g., secret: process.env.JWT_SECRET ?? 'fallback'

error Algorithms is not provided ↓

cause Missing required `algorithms` option in expressjwt config.

fix

Add algorithms: ['HS256'] (or your desired algorithm) to the options object.

Warnings

breaking v8 changed the exported function from default export `jwt` to named export `expressjwt`. ↓

fix Replace `import jwt from 'express-jwt'` with `import { expressjwt } from 'express-jwt'`.

breaking v8 changed the request property from `req.user` to `req.auth`. ↓

fix Access decoded payload via `req.auth` instead of `req.user`.

gotcha The `algorithms` option is required; not providing it will throw an error. ↓

fix Always pass `algorithms: ['HS256']` (or your chosen algorithm) in options.

gotcha Do not mix symmetric and asymmetric algorithms (e.g., HS256 and RS256) as it can lead to downgrade attacks. ↓

fix Use only one set of algorithms (symmetric or asymmetric) and validate against the expected algorithms list.

deprecated The `credentialsRequired` option defaulted to `true`; setting to `false` bypasses token validation entirely. ↓

fix If you want optional auth, consider using `.unless()` or handle missing tokens in your own middleware.

Install

npm install express-jwt

yarn add express-jwt

pnpm add express-jwt

Imports

expressjwt
wrong
```
import jwt from 'express-jwt'
```
correct
```
import { expressjwt } from 'express-jwt'
```
v8+ exports only named `expressjwt`; default export was removed.

ExpressJwtRequest

wrong

import { RequestWithAuth } from 'express-jwt'

correct

import { ExpressJwtRequest as RequestWithAuth } from 'express-jwt'

TypeScript only; re-exported as needed.

GetVerificationKey

wrong

import { GetVerificationKey } from 'express-jwt'

correct

import type { GetVerificationKey } from 'express-jwt'

Type-only import to avoid runtime errors when not used as a value.

Quickstart

Shows basic usage: importing expressjwt, setting up a protected route with secret and algorithms, and accessing the decoded payload from req.auth.

import { expressjwt } from 'express-jwt';
import express from 'express';

const app = express();

// Protected route
app.get(
  '/protected',
  expressjwt({
    secret: process.env.JWT_SECRET ?? 'my-secret',
    algorithms: ['HS256'],
  }),
  (req, res) => {
    // Access payload via req.auth
    if (!req.auth.admin) return res.sendStatus(401);
    res.json({ message: 'Protected data', user: req.auth });
  }
);

// Public route
app.get('/token', (req, res) => {
  res.send('No auth required');
});

app.listen(3000);