JWT in Node.js: Sign, Verify and Protect Express Routes

A JWT (JSON Web Token) is a string of three base64url parts, header.payload.signature, that a server gives a user at login and checks on every later request. The signature proves the server issued the token and nobody changed it, but the payload is only encoded, not encrypted, so anyone can read it. In Node.js you create one with new SignJWT(payload).sign(secret) from the jose package and check it with jwtVerify(token, secret).

import { SignJWT, jwtVerify } from 'jose';

// In a real app the secret comes from process.env.JWT_SECRET
const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');

const token = await new SignJWT({ role: 'admin' })
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject('user-42')
    .setIssuedAt()
    .setExpirationTime('1h')
    .sign(secret);

console.log(token.split('.').length, 'parts');

const { payload } = await jwtVerify(token, secret);
console.log(payload.sub, payload.role);

It prints 3 parts, then user-42 admin: jwtVerify checked the signature and the expiry and returned the payload. Change the secret passed to jwtVerify by one character and run it again: verification fails with signature verification failed.

What is inside a JWT

The header and the payload are JSON, encoded with base64url. Decoding them needs no key, which is why a JWT must never hold a password or anything else secret.

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const token = await new SignJWT({ name: 'Ada', role: 'editor' })
    .setProtectedHeader({ alg: 'HS256' })
    .sign(secret);

const [header, payload, signature] = token.split('.');

console.log(Buffer.from(header, 'base64url').toString());
console.log(Buffer.from(payload, 'base64url').toString());
console.log(signature.length);

The first two lines print {"alg":"HS256"} and {"name":"Ada","role":"editor"}, readable by anyone holding the token. The signature (43 characters for HS256) is what stops them from editing it: change editor to admin and the signature no longer matches.

Expiry and failed verification

setExpirationTime('15m') writes an exp claim, and jwtVerify rejects a token past it. Every rejection is an error with a code, so you can tell an expired token from a forged one.

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const expired = await new SignJWT({ sub: 'user-42' })
    .setProtectedHeader({ alg: 'HS256' })
    .setExpirationTime(1700000000) // a moment in 2023, long past
    .sign(secret);

try {
    await jwtVerify(expired, secret);
} catch (err) {
    console.log(err.code);
}

const forged = expired.slice(0, -2) + 'xx';
try {
    await jwtVerify(forged, secret);
} catch (err) {
    console.log(err.code);
}

The first check fails with ERR_JWT_EXPIRED and the second, whose signature was changed, with ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Both mean the same to your API (answer 401), but logging the code helps when debugging.

Protect an Express route with a Bearer token

The client logs in once, keeps the token and sends it in the Authorization header as Bearer <token>. A middleware verifies it and puts the payload on req.user for the route.

// GET /me
import express from 'express';
import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const app = express();
app.use(express.json());

app.post('/login', async (req, res) => {
    const { username, password } = req.body ?? {};
    // A real app looks the user up and checks a hashed password
    if (username !== 'ada' || password !== 'lovelace') {
        return res.status(401).json({ error: 'Wrong username or password' });
    }
    const token = await new SignJWT({ name: username })
        .setProtectedHeader({ alg: 'HS256' })
        .setSubject('user-1')
        .setExpirationTime('15m')
        .sign(secret);
    res.json({ token });
});

async function requireAuth(req, res, next) {
    const header = req.get('authorization') ?? '';
    const token = header.startsWith('Bearer ') ? header.slice(7) : null;
    if (!token) return res.status(401).json({ error: 'Missing token' });
    try {
        const { payload } = await jwtVerify(token, secret);
        req.user = payload;
        next();
    } catch {
        res.status(401).json({ error: 'Invalid or expired token' });
    }
}

app.get('/me', requireAuth, (req, res) => {
    res.json({ id: req.user.sub, name: req.user.name });
});

app.listen(3000);

The first request, GET /me with no token, gets 401 and Missing token. Send POST /login with the body {"username": "ada", "password": "lovelace"}, copy the token from the response, then send GET /me again with the header Authorization: Bearer <token>: the answer is {"id":"user-1","name":"ada"}.

The jsonwebtoken package

jsonwebtoken (npm install jsonwebtoken) is the other common choice. Its sign and verify are synchronous (with optional callbacks) instead of returning promises:

const jwt = require('jsonwebtoken');

const token = jwt.sign({ role: 'admin' }, process.env.JWT_SECRET, {
    subject: 'user-42',
    expiresIn: '1h',
});

const payload = jwt.verify(token, process.env.JWT_SECRET); // throws if invalid

Use jose for new code: it has no dependencies and also runs in edge runtimes and browsers. Tokens from either library are standard JWTs, so one can verify what the other signed.

Common mistakes

Using decode instead of verify. jwt.decode and decodeJwt read the payload without checking the signature, so a forged token passes. Only trust what verify returns.

A short or committed secret. A guessable HS256 secret lets attackers sign their own tokens. Use at least 32 random bytes, read it from process.env, and never commit it.

Tokens that never expire. Without exp, a leaked token works forever. Always set an expiry.