JSON Web Token (JWT) Implementation

Common errors

• TokenExpiredError: jwt expired

  cause The JWT has exceeded its 'exp' (expiration time) claim.
  fix Issue a new token with an updated expiration time, or refresh the token if using a refresh token mechanism.

• JsonWebTokenError: invalid signature

  cause The token's signature does not match the computed signature, likely due to a tampered token or an incorrect secret/public key used for verification.
  fix Ensure the same secret or public key (for asymmetric algorithms) that was used to sign the token is used to verify it. Check for any encoding issues with the key.

• JsonWebTokenError: jwt malformed

  cause The provided string is not a valid JWT format (e.g., missing segments, incorrect base64 encoding).
  fix Verify that the token string is complete, correctly encoded, and matches the 'header.payload.signature' structure of a JWT.

• NotBeforeError: jwt not active

  cause The token's 'nbf' (not before) claim indicates it should not be accepted yet.
  fix Wait until the 'nbf' time has passed before attempting to use or verify the token. Ensure the system clocks of the issuing and verifying servers are synchronized.

• JsonWebTokenError: secret or public key must be provided

  cause The `secretOrPrivateKey` parameter was omitted or was an empty/invalid value during signing or verification.
  fix Provide a valid string, buffer, or KeyObject for `secretOrPrivateKey` during both signing and verification operations. For private keys with passphrases, use `{ key, passphrase }`.

Warnings

• gotcha Claims like `exp` (expiration time) are only set by the `sign` function if the `payload` parameter is an object literal. If you pass a buffer or string, these claims will not be added or validated.
  Fix: Always use an object literal as the `payload` when you expect claims like `exp`, `nbf`, `aud`, `iss`, or `sub` to be automatically managed.
• breaking When signing with RSA algorithms, private keys with a modulus length shorter than 2048 bits will be rejected by default, resulting in an error.
  Fix: Use RSA private keys with a modulus length of 2048 bits or greater. If absolutely necessary for backward compatibility in non-production environments, set the `allowInsecureKeySizes: true` option (not recommended).
• gotcha When `expiresIn` or `notBefore` options are provided as a string without a time unit (e.g., `'120'`), the value is interpreted as milliseconds, not seconds, leading to unexpectedly short token lifespans.
  Fix: Always provide explicit time units for string-based `expiresIn` and `notBefore` values (e.g., `'120s'`, `'2h'`, `'7d'`) or use numeric values in seconds.
• gotcha There are no default values for common JWT claims such as `expiresIn`, `notBefore`, `audience`, `subject`, and `issuer`. If these are not explicitly provided, they will be omitted from the token.
  Fix: Always explicitly define desired claims (e.g., `expiresIn: '1h'`) either in the `options` object or directly within the `payload` object.
• gotcha The `mutatePayload: true` option directly modifies the original `payload` object passed to `jwt.sign` by adding or overwriting claims (like `iat`, `exp`). This can cause unexpected side effects if the original payload object is reused.
  Fix: Avoid `mutatePayload: true` unless you explicitly intend for the payload object to be modified. If you need to inspect the payload after claims are added, consider making a copy of the payload before signing or using the returned token's decoded payload.

Install

• npm install jsonwebtoken npm
• yarn add jsonwebtoken yarn
• pnpm add jsonwebtoken pnpm

Imports

• sign
  wrong:

  const sign = require('jsonwebtoken').sign;

  correct:

  import { sign } from 'jsonwebtoken';

  The `jsonwebtoken` package is a CommonJS module, but its exported functions like `sign` can be imported as named exports in an ESM context.

Quickstart

This quickstart demonstrates how to sign a JSON Web Token synchronously and asynchronously using a simple payload and a secret key, with an expiration time of one hour. It also shows basic error handling.

import { sign } from 'jsonwebtoken';

const payload = {
  userId: 'user123',
  email: 'test@example.com'
};

const secret = process.env.JWT_SECRET ?? 'your-very-strong-secret'; // Use a strong, secure secret in production

try {
  // Synchronous signing example
  const token = sign(payload, secret, { expiresIn: '1h' });
  console.log('Signed JWT:', token);

  // Asynchronous signing example
  sign(payload, secret, { expiresIn: '1h' }, (err, asyncToken) => {
    if (err) {
      console.error('Async signing error:', err);
      return;
    }
    console.log('Signed JWT (async):', asyncToken);
  });
} catch (error) {
  console.error('Error signing token:', error);
}