Nexmo Authentication: API Keys, Signatures, and JWTs (2026)

Authentication overview

Nexmo, now operating under the Vonage Communications APIs umbrella, provides several authentication mechanisms to secure access to its services. The choice of method typically depends on the specific API being called and the security requirements of the application. The most common methods involve using an API Key and API Secret, often augmented with request signing for server-to-server interactions. For client-side interactions, particularly with the Client SDKs for in-app voice and video, JSON Web Tokens (JWTs) are the preferred method for user authentication and authorization.

Proper authentication ensures that only authorized applications and users can interact with your Vonage account, preventing unauthorized usage and protecting sensitive data. Understanding when to use each method and how to implement it securely is crucial for integrating Vonage APIs effectively into your applications. The Vonage API Dashboard serves as the central hub for managing your API credentials, including generating API keys, secrets, and configuring signature secrets.

Supported authentication methods

Vonage APIs support a range of authentication methods tailored to different use cases. The primary methods are API Key and API Secret, request signing, and JSON Web Tokens (JWTs).

API Key and API Secret

This is the most fundamental authentication method for many Vonage APIs, including SMS, Voice, and Number Insight. You provide your API Key and API Secret with each request. The API Key identifies your account, and the API Secret authenticates the request. This method is suitable for server-to-server communication where the secret can be stored securely.

Request Signing

To enhance the security of requests made with an API Key and API Secret, Vonage recommends and sometimes requires request signing. Request signing involves generating a unique hash (signature) for each request using your API Secret and a shared secret key, which is then sent along with the request. The Vonage API then verifies this signature to ensure the request has not been tampered with and originated from a legitimate source. This protects against replay attacks and man-in-the-middle tampering. The signature is typically generated using HMAC-SHA1 or HMAC-SHA256 algorithms, as detailed in the Vonage signature authentication documentation.

JSON Web Tokens (JWTs)

JWTs are primarily used for authenticating users with Vonage's Client SDKs, such as the Voice and Video APIs, where client-side applications need to interact directly with Vonage services. A JWT is a compact, URL-safe means of representing claims to be transferred between two parties. The token is issued by your backend server after a user authenticates with your application. It contains claims about the user and is signed with a private key, ensuring its authenticity. The client-side application then uses this JWT to authenticate with the Vonage Client SDKs. This method provides a secure way to manage user-specific access without exposing your API Secret directly to client applications. More details on JWT-based authentication are available in the Vonage JWT documentation.

The following table summarizes the primary authentication methods:

Getting your credentials

All authentication credentials for Vonage APIs are managed through the Vonage API Dashboard.

1. Create a Vonage Account: If you don't already have one, sign up for a Vonage API account. Your initial account creation will likely generate your first API Key and API Secret.
2. Access the Dashboard: Log in to your Vonage API Dashboard.
3. Locate API Keys: Navigate to the "Settings" or "API Settings" section. Here, you will find your primary API Key and API Secret. It's crucial to treat your API Secret like a password and keep it confidential.
4. Generate Signature Secret: For APIs requiring request signing, you will also find an option to generate or view your "Signature Secret" in the same settings area. You can also rotate these secrets periodically for enhanced security.
5. Generate Private Key for JWTs: For JWT-based authentication, you'll need to generate a private key. In the dashboard, typically under "Applications" or a specific "Project," you can create a new application and generate a private key file (.key). This private key is used by your backend server to sign the JWTs that your client applications will use. Store this private key securely and never expose it to client-side code.

Remember to store your API Secret and private keys in secure environments, such as environment variables or secret management services, and never hardcode them directly into your application code or commit them to version control. For managing API keys, services like AWS Secrets Manager or Google Secret Manager can provide secure storage and retrieval, as described in AWS Secrets Manager documentation.

Authenticated request example

This example demonstrates how to send an authenticated SMS message using the Vonage SMS API with an API Key and API Secret, including request signing. We'll use Node.js for this example, leveraging the official Vonage Node.js SDK, which handles the intricacies of signing automatically.

First, ensure you have the Vonage Node.js SDK installed:

npm install @vonage/server-sdk

Next, use your API Key and API Secret to initialize the SDK and send a message. Make sure your API_KEY, API_SECRET, and SIGNATURE_SECRET are stored as environment variables for security.

const Vonage = require('@vonage/server-sdk');

const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
  signatureSecret: process.env.VONAGE_SIGNATURE_SECRET, // Required for signed requests
  privateKey: process.env.VONAGE_PRIVATE_KEY_PATH, // Only for JWT-based APIs (e.g., Voice/Video Client SDKs)
  applicationId: process.env.VONAGE_APPLICATION_ID  // Only for JWT-based APIs
}, { debug: true });

const from = 'VonageAPI'; // Your Vonage virtual number or alphanumeric sender ID
const to = '1234567890'; // Recipient's phone number
const text = 'Hello from Vonage, this is a signed message!';

vonage.message.sendSms(from, to, text, (err, responseData) => {
  if (err) {
    console.error('Error sending SMS:', err);
  } else {
    if (responseData.messages[0]['status'] === "0") {
      console.log("Message sent successfully.");
      console.log(responseData.messages[0]);
    } else {
      console.error(`Message failed with error: ${responseData.messages[0]['error-text']}`);
    }
  }
});

In this example, the SDK automatically handles the request signing process if signatureSecret is provided during initialization. For APIs that use JWTs, you would typically generate the JWT on your server and then pass it to your client-side application, which would then use the Vonage Client SDK to make authenticated calls. The Vonage Voice API documentation on JWT authentication provides further details on setting up JWTs for client-side applications.

Security best practices

Implementing strong security practices is paramount when working with any API that handles sensitive data or communication. For Vonage APIs, consider the following:

• Protect API Keys and Secrets: Never hardcode API keys, secrets, or private keys directly into your application code. Use environment variables, secret management services (e.g., Google Cloud Secret Manager), or configuration files that are not committed to version control.
• Enable Request Signing: Always use request signing for server-to-server API calls where supported. This adds an extra layer of security by verifying the request's origin and integrity, mitigating risks like replay attacks and data tampering.
• Rotate Credentials Regularly: Periodically rotate your API keys, secrets, and private keys. The Vonage API Dashboard provides tools to facilitate this. This minimizes the risk associated with compromised credentials over time.
• Use JWTs for Client-Side Authentication: For client-side applications interacting with Vonage Client SDKs, always use JSON Web Tokens (JWTs). Generate these tokens on your secure backend server and sign them with a private key. Never expose your private key to client-side code.
• Least Privilege Principle: If Vonage offers granular permissions (e.g., for different API keys or applications), configure your credentials with the minimum necessary permissions required for your application's functionality.
• Monitor API Usage: Regularly monitor your API usage logs for any unusual activity that might indicate unauthorized access or misuse of your credentials.
• Secure Webhooks: If your application receives webhooks from Vonage, always verify the signature of incoming webhooks to ensure they originate from Vonage and have not been tampered with. The Vonage documentation on securing webhooks provides guidance on this.
• Implement HTTPS: Ensure all communication with Vonage APIs occurs over HTTPS (TLS/SSL) to encrypt data in transit and prevent eavesdropping. Vonage APIs enforce HTTPS by default.
• Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could aid an attacker in identifying vulnerabilities.