Skip to content

Vonage JWT 1

Jump to bottom
github-actions edited this page Jul 1, 2025 · 4 revisions

Documentation

Documentation / Vonage JWT

Vonage JWT SDK for Node.js

GitHub Workflow Status Codecov Latest Release Contributor Covenant License

Vonage

This is the Vonage JWT SDK for Node.js. This package helps create JWT tokens to use with Vonage APIs.

For full API documentation refer to developer.vonage.com.

Installation

With NPM

npm install @vonage/jwt

With Yarn

yarn add @vonage/jwt

Usage

All you need to do is require('@vonage/jwt'), and use the returned object tocreate your own JWT token.

const { tokenGenerate } = require('@vonage/jwt');

const jwtToken = tokenGenerate(applicationId, privateKey, generatorOptions);

Parameters

  • applicationId: string - The Vonage Application Id.
  • privateKey: string | Buffer - The private key.
  • generatorOptions: GeneratorOptions - An object that can be used to set options for the token. See the jsonwebtoken for all options and claims. You can also pass in a Vonage acl

Testing

Run:

npm run test

Classes

InvalidApplicationIdError

Defined in: packages/jwt/lib/errors/invalidApplicationIdError.ts:9

InvalidMissingApplicationIdError` class for throwing an error when the application id is not a valid string. You can get the application ID from your developer dashboard. The ID will be a UUID that was generated when you created the application.

Extends

  • Error

Constructors

Constructor
new InvalidApplicationIdError(): InvalidApplicationIdError;

Defined in: packages/jwt/lib/errors/invalidApplicationIdError.ts:10

Returns

InvalidApplicationIdError

Overrides
Error.constructor

Properties

cause?
optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from
Error.cause
message
message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from
Error.message
name
name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from
Error.name
stack?
optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from
Error.stack
stackTraceLimit
static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:161

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from
Error.stackTraceLimit

Methods

captureStackTrace()
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:145

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters
targetObject

object

constructorOpt?

Function

Returns

void

Inherited from
Error.captureStackTrace
prepareStackTrace()
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:149

Parameters
err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from
Error.prepareStackTrace

InvalidPrivateKeyError

Defined in: packages/jwt/lib/errors/invalidPrivateKeyError.ts:10

InvalidPrivateKeyError class for throwing an error when the private key is invalid. The private key must either be the string of the key or a buffer from the key file. When you created the application, the private key would have been downloaded then. If you lost the key, you will need to regenrate the key.

Extends

  • Error

Constructors

Constructor
new InvalidPrivateKeyError(): InvalidPrivateKeyError;

Defined in: packages/jwt/lib/errors/invalidPrivateKeyError.ts:11

Returns

InvalidPrivateKeyError

Overrides
Error.constructor

Properties

cause?
optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from
Error.cause
message
message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from
Error.message
name
name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from
Error.name
stack?
optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from
Error.stack
stackTraceLimit
static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:161

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from
Error.stackTraceLimit

Methods

captureStackTrace()
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:145

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters
targetObject

object

constructorOpt?

Function

Returns

void

Inherited from
Error.captureStackTrace
prepareStackTrace()
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:149

Parameters
err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from
Error.prepareStackTrace

MissingApplicationIdError

Defined in: packages/jwt/lib/errors/missingApplicationIdError.ts:9

MissingApplicationIdError class for throwing an error when the application id is missing. You can get the application ID from your developer dashboard. The ID will be a UUID that was generated when you created the application.

Extends

  • Error

Constructors

Constructor
new MissingApplicationIdError(): MissingApplicationIdError;

Defined in: packages/jwt/lib/errors/missingApplicationIdError.ts:10

Returns

MissingApplicationIdError

Overrides
Error.constructor

Properties

cause?
optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from
Error.cause
message
message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from
Error.message
name
name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from
Error.name
stack?
optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from
Error.stack
stackTraceLimit
static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:161

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from
Error.stackTraceLimit

Methods

captureStackTrace()
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:145

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters
targetObject

object

constructorOpt?

Function

Returns

void

Inherited from
Error.captureStackTrace
prepareStackTrace()
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:149

Parameters
err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from
Error.prepareStackTrace

MissingPrivateKeyError

Defined in: packages/jwt/lib/errors/missingPrivateKeyError.ts:10

MissingPrivateKeyError class for throwing an error when the private key is missing. The private key must either be the string of the key or a buffer from the key file. When you created the application, the private key would have been downloaded then. If you lost the key, you will need to regenrate the key.

Extends

  • Error

Constructors

Constructor
new MissingPrivateKeyError(): MissingPrivateKeyError;

Defined in: packages/jwt/lib/errors/missingPrivateKeyError.ts:11

Returns

MissingPrivateKeyError

Overrides
Error.constructor

Properties

cause?
optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from
Error.cause
message
message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from
Error.message
name
name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from
Error.name
stack?
optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from
Error.stack
stackTraceLimit
static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:161

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from
Error.stackTraceLimit

Methods

captureStackTrace()
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:145

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters
targetObject

object

constructorOpt?

Function

Returns

void

Inherited from
Error.captureStackTrace
prepareStackTrace()
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:149

Parameters
err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from
Error.prepareStackTrace

Type Aliases

ACL

type ACL = object;

Defined in: packages/jwt/lib/types/acl.ts:19

Represents an Access Control List (ACL) with rules for different paths.

Properties

paths
paths: Record<string, ACLRule>;

Defined in: packages/jwt/lib/types/acl.ts:23

Rules associated with different paths.

ACLRule

type ACLRule = object;

Defined in: packages/jwt/lib/types/acl.ts:4

Represents a rule for Access Control List (ACL).

Properties

filters?
optional filters: Record<string, string | number | unknown | unknown[]>;

Defined in: packages/jwt/lib/types/acl.ts:13

Filters associated with this rule for more fine-grained control.

methods?
optional methods: ("POST" | "PUT" | "PATCH" | "GET" | "DELETE")[];

Defined in: packages/jwt/lib/types/acl.ts:8

An array of HTTP methods allowed by this rule.

Claims

type Claims = object;

Defined in: packages/jwt/lib/types/claims.ts:8

JWT claims.

See

https://developer.vonage.com/en/getting-started/concepts/authentication#claims

Properties

acl?
optional acl: ACL;

Defined in: packages/jwt/lib/types/claims.ts:33

Access Control List claim, provides access control information.

application_id?
optional application_id: string;

Defined in: packages/jwt/lib/types/claims.ts:44

Application ID claim, identifies the application that is the subject of the JWT.

exp?
optional exp: number;

Defined in: packages/jwt/lib/types/claims.ts:12

Expiration time of the JWT.

iat?
optional iat: number;

Defined in: packages/jwt/lib/types/claims.ts:38

Issued At claim, identifies the time at which the JWT was issued.

jti?
optional jti: string;

Defined in: packages/jwt/lib/types/claims.ts:22

JWT ID claim, provides a unique identifier for the JWT.

nbf?
optional nbf: number;

Defined in: packages/jwt/lib/types/claims.ts:28

Not Before claim, identifies the time before which the JWT must not be accepted for processing.

sub?
optional sub: string;

Defined in: packages/jwt/lib/types/claims.ts:17

Subject claim, identifies the principal that is the subject of the JWT.

GeneratorOptions

type GeneratorOptions = object;

Defined in: packages/jwt/lib/types/generatorOptions.ts:6

Claims to pass in for the token generator.

Indexable

[key: string]: unknown

Additional custom properties and values.

Properties

acl?
optional acl: ACL;

Defined in: packages/jwt/lib/types/generatorOptions.ts:35

Access control list.

exp?
optional exp: number;

Defined in: packages/jwt/lib/types/generatorOptions.ts:47

The time at which the JWT expires.

If set to a time less than issued_at, the token will expire in 15 minutes.

issued_at?
optional issued_at: number;

Defined in: packages/jwt/lib/types/generatorOptions.ts:15

The time at which the JWT was issued.

jti?
optional jti: string;

Defined in: packages/jwt/lib/types/generatorOptions.ts:25

JSON Web Token ID.

key?
optional key: string;

Defined in: packages/jwt/lib/types/generatorOptions.ts:40

Additional properties and values.

notBefore?
optional notBefore: number;

Defined in: packages/jwt/lib/types/generatorOptions.ts:30

The time before which the JWT is not yet valid.

subject?
optional subject: string;

Defined in: packages/jwt/lib/types/generatorOptions.ts:20

Subject of the token.

ttl?
optional ttl: number;

Defined in: packages/jwt/lib/types/generatorOptions.ts:10

Time to live in seconds.

Functions

tokenGenerate()

function tokenGenerate(
   applicationId, 
   privateKey, 
   opts?): string;

Defined in: packages/jwt/lib/tokenGenerate.ts:87

Generates a JWT token.

Parameters

applicationId

string

The application id.

privateKey

The private key as a string or buffer.

string | Buffer

opts?

GeneratorOptions

Optional generator options.

Returns

string

  • Returns the signed JWT token.

Throws

Throws an error if applicationId is missing.

Throws

Throws an error if privateKey is missing.

Throws

Throws an error if applicationId is not a string.

Throws

Throws an error if privateKey is not a string or buffer.

See

https://developer.vonage.com/en/getting-started/concepts/authentication#json-web-tokens

Examples

Generate a JWT token with default claims.

const privateKey = fs.readFileSync(__dirname + '/private.key');
const token = tokenGenerate(applicationId, privateKey);

Generate a JWT token with custom claims.

const privateKey = fs.readFileSync(__dirname + '/private.key');
const token = tokenGenerate(applicationId, privateKey, {
  subject: 'my-subject',
  acl: {
   paths: {
     '/*/users/**': {},
     '/*/conversations/**': {},
     '/*/sessions/**': {},
   },
  },
});

verifySignature()

function verifySignature(jwt, privateKey): boolean;

Defined in: packages/jwt/lib/verifySignature.ts:34

Verifies a JWT token

Parameters

jwt

string

The JSON Web Token to verify.

privateKey

The private key used to verify the JWT signature.

string | Buffer

Returns

boolean

Returns true if the JWT signature is verified successfully, otherwise returns false.

Throws

Throws an error if the private key is missing.

Throws

Throws an error if the private key is not a string or buffer.

Example

Validate a JWT token

const privateKey = fs.readFileSync('./private.key');
if (verifySignature(token, privateKey)) {
  console.log('JWT signature verified.');
} else {
  console.log('JWT signature verification failed.');
}
Clone this wiki locally