Managing Authentication

The Vonage CLI uses a flexible configuration system to manage your API credentials. It supports local or global configuration files and command-line flags for overriding these values, allowing you to tailor your setup based on your project needs or personal preferences.

Configuration

The CLI will load the configuration in the following order:

  1. Command line flags --api-key, --api-secret, --private-key, and --app-id.
  2. A local configuration file in the current working directory .vonagerc.
  3. A global configuration file in the .vonage folder in your home directory $HOME/.vonage/config.json.

Note: Only the CLI will read these values from .vonagerc. The Vonage SDKs require separate initialization with their own credentials.

Note: The contents of the private key will be stored inside the configuration file. This is by design to help ensure the key is not overwritten when new keys are generated.

Flags

Flag Description Type
--app-id The ID of the application to use. This is found in the "Applications" section of the dashboard or outputted with vonage apps. String
--privateKey The path or contents of the private key. The private key can only be accessed when the application is created or when you regenerate the keys in the dashboard. String
--apiKey The API key found in the "API settings" section of your dashboard. String
--apiSecret The API secret found in the "API Settings" section of your dashboard. String

Set Authentication

While you can use the CLI without configuring it, you will be required to pass in the flags when running a command.

Using the vonage auth set command is recommended to save you from typing them every time you run a command.

Flags

This uses the flags listed above in Configuration.

Example

vonage auth set `
--api-key='your-api-key' `
--api-secret='your-api-secret' `
--app-id='your-application-id' `
--private-key=C:\path\to\private.key

API Key: your-api-key
API Secret: your-**************
App ID: your-application-id
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key

Note: Running vonage auth set will not remove current values. Therefore, you can set just the API Key/Secret or App ID/Private Key individually. However, you will not be able to set the App ID and Private key without having the API key and secret set. This is due to how the command checks the credentials are valid.

Note: This command will also check the credentials are correct before committing.

Check Authentication

Verify that your authentication details are valid. By default, this will use the global configuration file. Checking credentials works as follows:

  1. The API Key and secret are checked by making a call to list the applications using the Applications API.
  2. The App ID and Private key are validated by fetching the application information, and using the public key along with the private key to ensure they are paired correctly.

Note: This command will not use the command line arguments. It will only check the configuration files.

Flags

Flag Description
--local Use the local configuration file (.vonagerc)

Example

Check the global configuration:

vonage auth check 

Global credentials found at: C:\Users\bob\.vonage\config.json

API Key: abcd1234
API Secret: abc**************
App ID: 00000000-0000-0000-0000-000000000000
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key

Check the local configuration:

vonage auth check --local

Global credentials found at: .vonagerc

API Key: abcd1234
API Secret: abc**************
App ID: 00000000-0000-0000-0000-000000000000
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key

Show Authentication

Display your current authentication configuration. This follows the configuration loading mentioned above and lets you know which configuration file the CLI is using.

Note: This command will also check the credentials are correct.

Flags

Flag Description
--show-all Show non-redacted private key and API secret.
--yaml Output in YAML format.
--json Output in JSON format.

Example

vonage auth show

Global credentials found at: C:\Users\bob\.vonage\config.json

API Key: your-api-key
API Secret: your-**************
App ID: your-application-id
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key