jsonwebtoken

Use jwt.sign() to create a new JWT. It can be used synchronously (returns the token string) or asynchronously (if a callback is provided).

Payload Types:

• Object literal: Recommended. Allows setting claims like exp or sub directly in the payload. If you use options.expiresIn, the library will automatically set the exp claim.
• Buffer or String: The payload will be treated as raw data. Note that exp or other claims will not be set automatically if the payload is not an object literal.

Key Options:

• algorithm: The signing algorithm (default: HS256).
• expiresIn: Time span for token validity (e.g., 60, '2 days', '10h'). Numeric values are treated as seconds. Strings use vercel/ms logic (e.g., '120' defaults to 120ms unless units are provided).
• notBefore: Time span for the nbf claim.
• mutatePayload: If true, the function modifies the original payload object directly.
• allowInsecureKeySizes: If true, allows RSA private keys with a modulus below 2048.

Important Note on Claims: You can provide claims like exp, nbf, aud, sub, and iss directly in the payload object, or via options. You cannot include the same claim in both places.

var jwt = require('jsonwebtoken');

// Synchronous Sign with default (HMAC SHA256)
var token = jwt.sign({ foo: 'bar' }, 'shhhhh');

// Synchronous Sign with RSA SHA256
var privateKey = fs.readFileSync('private.key');
var token = jwt.sign({ foo: 'bar' }, privateKey, { algorithm: 'RS256' });

// Sign asynchronously
jwt.sign({ foo: 'bar' }, privateKey, { algorithm: 'RS256' }, function(err, token) {
  console.log(token);
});

// Signing a token with 1 hour of expiration using expiresIn
jwt.sign({
  data: 'foobar'
}, 'secret', { expiresIn: '1h' });

Use jwt.verify() to validate a token's signature and claims.

• Synchronous: If no callback is provided, it returns the decoded payload or throws an error if invalid.
• Asynchronous: If a callback is provided, it calls the callback with the decoded payload or an error.

Key Options:

• algorithms: A list of allowed algorithms (e.g., ['HS256', 'HS384']). If not specified, defaults are chosen based on the key type (secret $\rightarrow$ HMAC, rsa $\rightarrow$ RSA, ec $\rightarrow$ ECDSA).
• audience: Validates the aud claim against a string, regex, or array of strings/regex.
• issuer: Validates the iss claim against a string or array of strings.
• clockTolerance: Number of seconds to tolerate for nbf and exp checks to account for clock drift.
• maxAge: Maximum allowed age for tokens (e.g., '2 days').
• ignoreExpiration: If true, skips exp validation.
• complete: If true, returns an object containing { payload, header, signature } instead of just the payload.

Security Warning: When the token comes from an untrusted source, treat the returned payload as untrusted user input. Sanitize it before use.

var jwt = require('jsonwebtoken');
var cert = fs.readFileSync('public.pem');

// Verify a token symmetric - synchronous
var decoded = jwt.verify(token, 'shhhhh');

// Verify a token asymmetric
jwt.verify(token, cert, function(err, decoded) {
  console.log(decoded.foo);
});

// Verify with specific audience and issuer
jwt.verify(token, cert, { audience: 'urn:foo', issuer: 'urn:issuer' }, function(err, decoded) {
  // if mismatch, err == invalid audience/issuer
});

// Verify using a getKey callback (e.g., for JWKS)
function getKey(header, callback){
  client.getSigningKey(header.kid, function(err, key) {
    var signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

jwt.verify(token, getKey, options, function(err, decoded) {
  console.log(decoded.foo);
});

The library supports a wide range of digital signature and MAC algorithms. When signing or verifying, you can specify the algorithm in the options object.

When using the callback version of jwt.verify(), the first argument err contains error details if verification fails. There are three primary error types you should handle:

1. TokenExpiredError: Thrown when the exp claim in the token is in the past. The error object includes expiredAt.
2. NotBeforeError: Thrown when the current time is before the nbf (not before) claim. The error object includes date.
3. JsonWebTokenError: A general error for various invalid states, such as malformed tokens, invalid signatures, or mismatches in aud (audience), iss (issuer), jti (JWT ID), or sub (subject).

Always check for the existence of err in your callback before processing the decoded payload.

// Example: Handling a TokenExpiredError
jwt.verify(token, 'shhhhh', function(err, decoded) {
  if (err) {
    if (err.name === 'TokenExpiredError') {
      console.log('Token expired at:', err.expiredAt);
    } else if (err.name === 'JsonWebTokenError') {
      console.log('Invalid token:', err.message);
    }
  }
});