Vonage Auth

Vonage Auth

---

Documentation / Vonage Auth

Vonage Auth

Enumerations

AlgorithmTypes

Defined in: packages/auth/lib/enums/AlgroithmTypes.ts:8

Enumeration of supported algorithm types for HMAC hashing.

Remarks

Ensure to select an algorithm that adheres to your security requirements and is supported by the API endpoint you're interacting with.

Enumeration Members

Enumeration Member	Value	Description	Defined in
md5hash	"MD5HASH"	Represents the MD5 hash algorithm	packages/auth/lib/enums/AlgroithmTypes.ts:10
md5hmac	"MD5HMAC"	Represents the HMAC-MD5 hash algorithm, which uses a secret key for hashing.	packages/auth/lib/enums/AlgroithmTypes.ts:13
sha1hmac	"SHA1HMAC"	Represents the HMAC-SHA1 hash algorithm, which uses a secret key for hashing.	packages/auth/lib/enums/AlgroithmTypes.ts:16
sha256hmac	"SHA256HMAC"	Represents the HMAC-SHA256 hash algorithm, which uses a secret key for hashing.	packages/auth/lib/enums/AlgroithmTypes.ts:19
sha512hmac	"SHA512HMAC"	Represents the HMAC-SHA512 hash algorithm, which uses a secret key for hashing.	packages/auth/lib/enums/AlgroithmTypes.ts:22

Classes

Auth

Defined in: packages/auth/lib/auth.ts:45

Authentication class used for generating Authentication headers and query parameters.

Remarks

This client is only available as a standalone client. It cannot be instantiated from the server-sdk package.

Example

Create a standard authentication object.

import { Auth } from '@vonage/auth';

const auth = new Auth({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});

Implements

• AuthInterface

Constructors

new Auth()

new Auth(opts?): Auth

Defined in: packages/auth/lib/auth.ts:79

Parameters

opts?

AuthParams

Returns

Auth

Properties

apiKey

apiKey: string;

Defined in: packages/auth/lib/auth.ts:49

The API key used to authenticate requests. It may be omitted if using JWT or signature authentication. This value can be found in your Vonage Developer Dashboard.

Implementation of

AuthInterface

apiSecret

apiSecret: string;

Defined in: packages/auth/lib/auth.ts:54

The API secret used to authenticate requests. It may be omitted if using JWT or signature authentication. This value can be found in your Vonage Developer Dashboard.

Implementation of

AuthInterface

applicationId?

optional applicationId: null | string;

Defined in: packages/auth/lib/auth.ts:66

The application ID used in conjunction with the private key for JWT authentication. It may be omitted if using API key/secret or signature authentication. This value can be found in your Vonage Developer Dashboard.

Implementation of

AuthInterface

jwtOptions

jwtOptions: GeneratorOptions;

Defined in: packages/auth/lib/auth.ts:77

Options for generating JWTs, including the JWT issuer (application ID) and subject (user ID).

Implementation of

AuthInterface

privateKey?

optional privateKey: null | string;

Defined in: packages/auth/lib/auth.ts:60

The private key used for JWT authentication. It can be provided as a string (read from a file) or as a Buffer (opened directly from a file). This key is downloaded when you create an application in your Vonage Developer Dashboard and may be omitted if using API key/secret or signature authentication.

Implementation of

AuthInterface

signature?

optional signature: null | SignedHashParams;

Defined in: packages/auth/lib/auth.ts:72

An object containing parameters for signature authentication, including the secret and algorithm. It may be omitted if using API key/secret or JWT authentication.

Implementation of

AuthInterface

Methods

createBasicHeader()

createBasicHeader(): Promise<string>

Defined in: packages/auth/lib/auth.ts:174

Generates a basic authentication header.

Returns

Promise<string>

• A promise that resolves with the generated basic authentication header.

Throws

• Thrown when the API key is missing.

Throws

• Thrown when the API secret is missing.

Throws

• Thrown when the API key is not a valid string.

Throws

• Thrown when the API secret is not a valid string.

Example

Generate a basic authentication headers

const basicAuthHeader = await auth.createBasicHeader();

Implementation of

AuthInterface

createBearerHeader()

createBearerHeader(): Promise<string>

Defined in: packages/auth/lib/auth.ts:209

Generates a bearer authentication header.

Returns

Promise<string>

• A promise that resolves with the generated bearer authentication header.

Example

Generate a bearer authentication headers

const bearerAuthHeader = await auth.createBearerHeader();

Implementation of

AuthInterface

createSignatureHash()

createSignatureHash<T>(params): Promise<AuthSignedParams & T>

Defined in: packages/auth/lib/auth.ts:248

Generates a signature hash for authentication, merging it with provided parameters.

Type Parameters

• T

Type of the parameters to merge with.

Parameters

params

AuthSignedParams & T

Parameters to merge with the generated signature hash.

Returns

Promise<AuthSignedParams & T>

• A promise that resolves with the merged signature hash and parameters.

Throws

• Thrown when the API key is missing.

Throws

• Thrown when the API key is not a valid string.

Throws

• Thrown when the signature algorithm is missing.

Throws

• Thrown when the API secret is missing.

Throws

• Thrown when the API secret is not a valid string.

Throws

• Thrown when an invalid signature algorithm is provided.

Example

Generate a signature hash

const signatureHash = await auth.createSignatureHash({
  to: '15555555555',
  from: '15555555556',
  text: 'Hello from Vonage SMS API',
  timestamp: '1516878400',
  sig: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
});

Implementation of

AuthInterface

getQueryParams()

getQueryParams<T>(params?): Promise<AuthQueryParams & T>

Defined in: packages/auth/lib/auth.ts:130

Generates query parameters for authentication, optionally merging with provided parameters.

Type Parameters

• T

Parameters

params?

AuthQueryParams & T

Additional parameters to merge with the generated authentication query parameters.

Returns

Promise<AuthQueryParams & T>

• A promise that resolves with the merged authentication query parameters.

Throws

• Thrown when the API key is missing.

Throws

• Thrown when the API secret is missing.

Throws

• Thrown when the API key is not a valid string.

Throws

• Thrown when the API secret is not a valid string.

Examples

Generate query parameters

const queryParams = await auth.getQueryParams();

Generate query parameters and merge with additional Parameters

const queryParams = await auth.getQueryParams({
  to: '15555555555',
  from: '15555555556',
  text: 'Hello from Vonage SMS API'
});

Implementation of

AuthInterface

---

InvalidApiKeyError

Defined in: packages/auth/lib/errors/InvalidApiKeyError.ts:10

Error class representing a specific error scenario where an API key is provided but is not a valid string.

This error is thrown when an API request is made with an API key that does not meet the expected format or type (string).

Extends

• Error

Constructors

new InvalidApiKeyError()

new InvalidApiKeyError(): InvalidApiKeyError

Defined in: packages/auth/lib/errors/InvalidApiKeyError.ts:11

Returns

InvalidApiKeyError

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

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:98

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:100

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:91

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

---

InvalidApiSecretError

Defined in: packages/auth/lib/errors/InvalidApiSecretError.ts:10

Error class representing a specific error scenario where an API secret is provided but is not a valid string.

This error is thrown when an API request is made with an API secret that does not meet the expected format or type (string).

Extends

• Error

Constructors

new InvalidApiSecretError()

new InvalidApiSecretError(): InvalidApiSecretError

Defined in: packages/auth/lib/errors/InvalidApiSecretError.ts:11

Returns

InvalidApiSecretError

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

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:98

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:100

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:91

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

---

InvalidSignatureAlgorithmError

Defined in: packages/auth/lib/errors/InvalidSignatureAlgroithmError.ts:10

Error class representing a specific error scenario where an invalid signature algorithm is provided.

This error is thrown when an API request is made with a signature algorithm that is not supported or recognized.

Extends

• Error

Constructors

new InvalidSignatureAlgorithmError()

new InvalidSignatureAlgorithmError(): InvalidSignatureAlgorithmError

Defined in: packages/auth/lib/errors/InvalidSignatureAlgroithmError.ts:11

Returns

InvalidSignatureAlgorithmError

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

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:98

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:100

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:91

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

---

MissingApiKeyError

Defined in: packages/auth/lib/errors/MissingApiKeyError.ts:10

Error class representing a specific error scenario where an API key is missing in the request.

This error is thrown when an API request is made without providing the necessary API key for authentication.

Extends

• Error

Constructors

new MissingApiKeyError()

new MissingApiKeyError(): MissingApiKeyError

Defined in: packages/auth/lib/errors/MissingApiKeyError.ts:11

Returns

MissingApiKeyError

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

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:98

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:100

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:91

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

---

MissingApiSecretError

Defined in: packages/auth/lib/errors/MissingApiSecretError.ts:10

Error class representing a specific error scenario where an API secret is missing in the request.

This error is thrown when an API request is made without providing the necessary API secret for authentication.

Extends

• Error

Constructors

new MissingApiSecretError()

new MissingApiSecretError(): MissingApiSecretError

Defined in: packages/auth/lib/errors/MissingApiSecretError.ts:11

Returns

MissingApiSecretError

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

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:98

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:100

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:91

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

---

MissingSignatureError

Defined in: packages/auth/lib/errors/MissingSignatureError.ts:12

Error class representing a specific error scenario where a signature algorithm is expected but missing in the request.

This error is thrown when an API request is made without providing the necessary signature algorithm for authentication.

Users should select a value from the AlgorithmTypes enum.

Extends

• Error

Constructors

new MissingSignatureError()

new MissingSignatureError(): MissingSignatureError

Defined in: packages/auth/lib/errors/MissingSignatureError.ts:13

Returns

MissingSignatureError

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

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:98

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:100

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: packages/auth/node_modules/@types/node/globals.d.ts:91

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

Interfaces

AuthInterface

Defined in: packages/auth/lib/interfaces/AuthInterface.ts:10

Interface defining the methods for handling various authentication mechanisms and parameter generation.

Extends

• AuthParams

Properties

apiKey?

optional apiKey: null | string;

Defined in: packages/auth/lib/types/AuthParams.ts:13

The API key used to authenticate requests. It may be omitted if using JWT or signature authentication. This value can be found in your Vonage Developer Dashboard.

Inherited from

AuthParams.apiKey

apiSecret?

optional apiSecret: null | string;

Defined in: packages/auth/lib/types/AuthParams.ts:20

The API secret used to authenticate requests. It may be omitted if using JWT or signature authentication. This value can be found in your Vonage Developer Dashboard.

Inherited from

AuthParams.apiSecret

applicationId?

optional applicationId: null | string;

Defined in: packages/auth/lib/types/AuthParams.ts:36

The application ID used in conjunction with the private key for JWT authentication. It may be omitted if using API key/secret or signature authentication. This value can be found in your Vonage Developer Dashboard.

Inherited from

AuthParams.applicationId

jwtOptions?

optional jwtOptions: GeneratorOptions;

Defined in: packages/auth/lib/types/AuthParams.ts:49

Options for generating JWTs, including the JWT issuer (application ID) and subject (user ID).

Inherited from

AuthParams.jwtOptions

privateKey?

optional privateKey: null | string | Buffer;

Defined in: packages/auth/lib/types/AuthParams.ts:29

The private key used for JWT authentication. It can be provided as a string (read from a file) or as a Buffer (opened directly from a file). This key is downloaded when you create an application in your Vonage Developer Dashboard and may be omitted if using API key/secret or signature authentication.

Inherited from

AuthParams.privateKey

signature?

optional signature: null | SignedHashParams;

Defined in: packages/auth/lib/types/AuthParams.ts:43

An object containing parameters for signature authentication, including the secret and algorithm. It may be omitted if using API key/secret or JWT authentication.

Inherited from

AuthParams.signature

Methods

createBasicHeader()

createBasicHeader(): Promise<string>

Defined in: packages/auth/lib/interfaces/AuthInterface.ts:41

Asynchronously generates a basic authentication header.

Returns

Promise<string>

• A promise that resolves with the generated basic authentication header.

createBearerHeader()

createBearerHeader(): Promise<string>

Defined in: packages/auth/lib/interfaces/AuthInterface.ts:49

Asynchronously generates a bearer authentication header.

Returns

Promise<string>

• A promise that resolves with the generated bearer authentication header.

createSignatureHash()

createSignatureHash<T>(params): Promise<AuthSignedParams & T>

Defined in: packages/auth/lib/interfaces/AuthInterface.ts:33

Asynchronously generates a signature hash for authentication, merging it with provided parameters.

Type Parameters

• T

Type of the parameters to merge with.

Parameters

params

T

Parameters to merge with the generated signature hash.

Returns

Promise<AuthSignedParams & T>

• A promise that resolves with the merged signature hash and parameters.

getQueryParams()

getQueryParams<T>(params?): Promise<AuthQueryParams & T>

Defined in: packages/auth/lib/interfaces/AuthInterface.ts:21

Asynchronously generates query parameters for authentication, optionally merging with provided parameters.

Type Parameters

• T

Type of the additional parameters to merge with.

Parameters

params?

T

Additional parameters to merge with the generated authentication query parameters.

Returns

Promise<AuthQueryParams & T>

• A promise that resolves with the merged authentication query parameters.

Type Aliases

AuthParams

type AuthParams = object;

Defined in: packages/auth/lib/types/AuthParams.ts:7

Represents the authentication parameters required for API requests.

Type declaration

apiKey?

optional apiKey: string | null;

The API key used to authenticate requests. It may be omitted if using JWT or signature authentication. This value can be found in your Vonage Developer Dashboard.

apiSecret?

optional apiSecret: string | null;

The API secret used to authenticate requests. It may be omitted if using JWT or signature authentication. This value can be found in your Vonage Developer Dashboard.

applicationId?

optional applicationId: string | null;

The application ID used in conjunction with the private key for JWT authentication. It may be omitted if using API key/secret or signature authentication. This value can be found in your Vonage Developer Dashboard.

jwtOptions?

optional jwtOptions: GeneratorOptions;

Options for generating JWTs, including the JWT issuer (application ID) and subject (user ID).

privateKey?

optional privateKey: string | Buffer | null;

The private key used for JWT authentication. It can be provided as a string (read from a file) or as a Buffer (opened directly from a file). This key is downloaded when you create an application in your Vonage Developer Dashboard and may be omitted if using API key/secret or signature authentication.

signature?

optional signature: SignedHashParams | null;

An object containing parameters for signature authentication, including the secret and algorithm. It may be omitted if using API key/secret or JWT authentication.

---

AuthQueryParams

type AuthQueryParams = object;

Defined in: packages/auth/lib/types/AuthQueryParams.ts:9

Represents the query parameters used for API request authentication.

Type declaration

api_key

api_key: string;

The API key used to authenticate requests. This value can be found in your Vonage Developer Dashboard.

api_secret

api_secret: string;

The API secret used to authenticate requests. This value can also be found in your Vonage Developer Dashboard.

Deprecated

This method of authentication, using API credentials in query parameters, is outdated and not recommended due to security concerns. Consider using more secure authentication methods, such as JWT or signature authentication.

---

AuthSignedParams

type AuthSignedParams = object;

Defined in: packages/auth/lib/types/AuthSignedParams.ts:12

Represents the parameters used for HMAC signature-based API request authentication.

Note: Not all API endpoints support this method of authentication. Please refer to the specific API documentation to determine if HMAC signature authentication is supported.

For more information on signing requests, visit: https://developer.vonage.com/en/getting-started/concepts/signing-messages

Type declaration

api_key

api_key: string;

The API key used to authenticate requests. This value can be found in your Vonage Developer Dashboard.

sig?

optional sig: string;

The generated signature, used to verify the authenticity of the request. It's typically generated by hashing the request parameters with a secret key.

timestamp?

optional timestamp: string;

The UNIX timestamp when the request is made. Utilized to prevent replay attacks by making each signature unique to a specific time window.

---

SignedHashParams

type SignedHashParams = object;

Defined in: packages/auth/lib/types/SignedHashParams.ts:7

Represents the parameters required for generating a signed hash.

Type declaration

algorithm

algorithm: AlgorithmTypes;

Specifies the algorithm type used for signing the hash. Utilizes the algorithm types defined in the AlgorithmTypes enum.

secret

secret: string;

The secret key used to sign the hash, ensuring the integrity and authenticity of the message. It should be kept private and secure.