-
Notifications
You must be signed in to change notification settings - Fork 178
Vonage Auth
Vonage Auth • Docs
Documentation / Vonage Auth
Enumeration of supported algorithm types for HMAC hashing.
Ensure to select an algorithm that adheres to your security requirements and is supported by the API endpoint you're interacting with.
| 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 |
Authentication class used for generating Authentication headers and query parameters.
This client is only available as a standalone client. It cannot be instantiated from the server-sdk package.
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,
});new Auth(opts?): Auth• opts?: AuthParams
apiKey: string;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: string;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.
optional applicationId: null | string;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: GeneratorOptions;Options for generating JWTs, including the JWT issuer (application ID) and subject (user ID).
optional privateKey: null | string;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.
optional signature: null | SignedHashParams;An object containing parameters for signature authentication, including the secret and algorithm. It may be omitted if using API key/secret or JWT authentication.
createBasicHeader(): Promise<string>Generates a basic authentication header.
Promise<string>
- A promise that resolves with the generated basic authentication header.
- Thrown when the API key is missing.
- Thrown when the API secret is missing.
- Thrown when the API key is not a valid string.
- Thrown when the API secret is not a valid string.
Generate a basic authentication headers
const basicAuthHeader = await auth.createBasicHeader();createBearerHeader(): Promise<string>Generates a bearer authentication header.
Promise<string>
- A promise that resolves with the generated bearer authentication header.
Generate a bearer authentication headers
const bearerAuthHeader = await auth.createBearerHeader();createSignatureHash<T>(params): Promise<AuthSignedParams & T>Generates a signature hash for authentication, merging it with provided parameters.
• T
Type of the parameters to merge with.
• params: AuthSignedParams & T
Parameters to merge with the generated signature hash.
Promise<AuthSignedParams & T>
- A promise that resolves with the merged signature hash and parameters.
- Thrown when the API key is missing.
- Thrown when the API key is not a valid string.
- Thrown when the signature algorithm is missing.
- Thrown when the API secret is missing.
- Thrown when the API secret is not a valid string.
- Thrown when an invalid signature algorithm is provided.
Generate a signature hash
const signatureHash = await auth.createSignatureHash({
to: '15555555555',
from: '15555555556',
text: 'Hello from Vonage SMS API',
timestamp: '1516878400',
sig: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
});getQueryParams<T>(params?): Promise<AuthQueryParams & T>Generates query parameters for authentication, optionally merging with provided parameters.
• T
• params?: AuthQueryParams & T
Additional parameters to merge with the generated authentication query parameters.
Promise<AuthQueryParams & T>
- A promise that resolves with the merged authentication query parameters.
- Thrown when the API key is missing.
- Thrown when the API secret is missing.
- Thrown when the API key is not a valid string.
- Thrown when the API secret is not a valid string.
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'
});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).
Error
new InvalidApiKeyError(): InvalidApiKeyErrorError.constructor
packages/auth/lib/errors/InvalidApiKeyError.ts:11
message: string;Error.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name: string;Error.name
node_modules/typescript/lib/lib.es5.d.ts:1076
optional stack: string;Error.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
static optional prepareStackTrace: (err, stackTraces) => any;Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static stackTraceLimit: number;Error.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static captureStackTrace(targetObject, constructorOpt?): voidCreate .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
Error.captureStackTrace
node_modules/@types/node/globals.d.ts:21
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).
Error
new InvalidApiSecretError(): InvalidApiSecretErrorError.constructor
packages/auth/lib/errors/InvalidApiSecretError.ts:11
message: string;Error.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name: string;Error.name
node_modules/typescript/lib/lib.es5.d.ts:1076
optional stack: string;Error.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
static optional prepareStackTrace: (err, stackTraces) => any;Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static stackTraceLimit: number;Error.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static captureStackTrace(targetObject, constructorOpt?): voidCreate .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
Error.captureStackTrace
node_modules/@types/node/globals.d.ts:21
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.
Error
new InvalidSignatureAlgorithmError(): InvalidSignatureAlgorithmErrorInvalidSignatureAlgorithmError
Error.constructor
packages/auth/lib/errors/InvalidSignatureAlgroithmError.ts:11
message: string;Error.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name: string;Error.name
node_modules/typescript/lib/lib.es5.d.ts:1076
optional stack: string;Error.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
static optional prepareStackTrace: (err, stackTraces) => any;Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static stackTraceLimit: number;Error.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static captureStackTrace(targetObject, constructorOpt?): voidCreate .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
Error.captureStackTrace
node_modules/@types/node/globals.d.ts:21
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.
Error
new MissingApiKeyError(): MissingApiKeyErrorError.constructor
packages/auth/lib/errors/MissingApiKeyError.ts:11
message: string;Error.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name: string;Error.name
node_modules/typescript/lib/lib.es5.d.ts:1076
optional stack: string;Error.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
static optional prepareStackTrace: (err, stackTraces) => any;Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static stackTraceLimit: number;Error.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static captureStackTrace(targetObject, constructorOpt?): voidCreate .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
Error.captureStackTrace
node_modules/@types/node/globals.d.ts:21
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.
Error
new MissingApiSecretError(): MissingApiSecretErrorError.constructor
packages/auth/lib/errors/MissingApiSecretError.ts:11
message: string;Error.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name: string;Error.name
node_modules/typescript/lib/lib.es5.d.ts:1076
optional stack: string;Error.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
static optional prepareStackTrace: (err, stackTraces) => any;Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static stackTraceLimit: number;Error.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static captureStackTrace(targetObject, constructorOpt?): voidCreate .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
Error.captureStackTrace
node_modules/@types/node/globals.d.ts:21
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.
Error
new MissingSignatureError(): MissingSignatureErrorError.constructor
packages/auth/lib/errors/MissingSignatureError.ts:13
message: string;Error.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name: string;Error.name
node_modules/typescript/lib/lib.es5.d.ts:1076
optional stack: string;Error.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
static optional prepareStackTrace: (err, stackTraces) => any;Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static stackTraceLimit: number;Error.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static captureStackTrace(targetObject, constructorOpt?): voidCreate .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
Error.captureStackTrace
node_modules/@types/node/globals.d.ts:21
Interface defining the methods for handling various authentication mechanisms and parameter generation.
optional apiKey: null | string;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.
AuthParams.apiKey
packages/auth/lib/types/AuthParams.ts:13
optional apiSecret: null | string;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.
AuthParams.apiSecret
packages/auth/lib/types/AuthParams.ts:20
optional applicationId: null | string;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.
AuthParams.applicationId
packages/auth/lib/types/AuthParams.ts:36
optional jwtOptions: GeneratorOptions;Options for generating JWTs, including the JWT issuer (application ID) and subject (user ID).
AuthParams.jwtOptions
packages/auth/lib/types/AuthParams.ts:49
optional privateKey: null | string | Buffer;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.
AuthParams.privateKey
packages/auth/lib/types/AuthParams.ts:29
optional signature: null | SignedHashParams;An object containing parameters for signature authentication, including the secret and algorithm. It may be omitted if using API key/secret or JWT authentication.
AuthParams.signature
packages/auth/lib/types/AuthParams.ts:43
createBasicHeader(): Promise<string>Asynchronously generates a basic authentication header.
Promise<string>
- A promise that resolves with the generated basic authentication header.
packages/auth/lib/interfaces/AuthInterface.ts:41
createBearerHeader(): Promise<string>Asynchronously generates a bearer authentication header.
Promise<string>
- A promise that resolves with the generated bearer authentication header.
packages/auth/lib/interfaces/AuthInterface.ts:49
createSignatureHash<T>(params): Promise<AuthSignedParams & T>Asynchronously generates a signature hash for authentication, merging it with provided parameters.
• T
Type of the parameters to merge with.
• params: T
Parameters to merge with the generated signature hash.
Promise<AuthSignedParams & T>
- A promise that resolves with the merged signature hash and parameters.
packages/auth/lib/interfaces/AuthInterface.ts:33
getQueryParams<T>(params?): Promise<AuthQueryParams & T>Asynchronously generates query parameters for authentication, optionally merging with provided parameters.
• T
Type of the additional parameters to merge with.
• params?: T
Additional parameters to merge with the generated authentication query parameters.
Promise<AuthQueryParams & T>
- A promise that resolves with the merged authentication query parameters.
packages/auth/lib/interfaces/AuthInterface.ts:21
type AuthParams: object;Represents the authentication parameters required for API requests.
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.
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.
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.
optional jwtOptions: GeneratorOptions;Options for generating JWTs, including the JWT issuer (application ID) and subject (user ID).
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.
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.
packages/auth/lib/types/AuthParams.ts:7
type AuthQueryParams: object;Represents the query parameters used for API request authentication.
api_key: string;The API key used to authenticate requests. This value can be found in your Vonage Developer Dashboard.
api_secret: string;The API secret used to authenticate requests. This value can also be found in your Vonage Developer Dashboard.
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.
packages/auth/lib/types/AuthQueryParams.ts:9
type AuthSignedParams: object;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
api_key: string;The API key used to authenticate requests. This value can be found in your Vonage Developer Dashboard.
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.
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.
packages/auth/lib/types/AuthSignedParams.ts:12
type SignedHashParams: object;Represents the parameters required for generating a signed hash.
algorithm: AlgorithmTypes;Specifies the algorithm type used for signing the hash. Utilizes the
algorithm types defined in the AlgorithmTypes enum.
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.