Authentication

Verify API supports two types of authentication:

• Basic Authentication
• JWT

When should you use Basic Authentication or JWT?

Verify V2 supports two authentication methods: Basic authentication and JWT Bearer authentication. Understanding the differences between them is important to ensure a smooth migration and to take full advantage of V2 capabilities.

You can use either option, but not both at the same time. In general, we recommend using JWT authentication when working with the Verify API. While Basic authentication is easier for getting started, it does not support the Silent Authentication channel.

Basic Authentication

Basic Authentication sends your API Key and API Secret Base64-encoded in the Authorization header. You can find these credentials in your API settings in the Vonage Dashboard.

It is the simplest way to get started with Verify V2, since no Vonage Application setup is required, and your credentials are immediately available from the Vonage Dashboard.

How It Works

Authorization: Basic <base64(api_key:api_secret)>

Create the Request Header

• First, concatenate your API Key and Secret: API_KEY:API_SECRET.
• Then, Base64 encode the result. Learn more here.
• Finally, send it in the request as Authorization: Basic BASE64_ENCODED_STRING.

You can do this within your application code - for example, in JavaScript:

const credentials = btoa('YOUR_API_KEY:YOUR_API_SECRET');

const response = await fetch('https://api-eu.vonage.com/v2/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + credentials
  },
  body: JSON.stringify({ ... })
});

Example Request

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

You can generate the Base64-encoded string from api_key:api_secret using any standard Base64 encoding tool or library.

Limitations

Basic Auth gives access to the core Verify V2 request flow (send, check, cancel, trigger next workflow), but there are two important limitations:

• Callbacks/webhooks are not supported. Receiving event or summary callbacks requires JWT Bearer authentication, along with a Vonage Application configured with a Status URL.
• ACL (Access Control List) support is not available. JWT tokens allow you to scope permissions to specific API endpoints, which is not possible with Basic Auth.

Given these limitations, Basic Auth is best suited for initial testing and POC integrations. For production deployments, JWT Bearer authentication is strongly recommended.

JWT

A JWT (JSON Web Token) is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. The object can optionally be encrypted and signed with a private/public key.

JWT Bearer Authentication uses a JSON Web Token signed with your Vonage Application's private key. This method unlocks the full capabilities of Verify V2, including event and summary callbacks, webhook configuration, and ACL-scoped tokens.

How It Works

Authorization: Bearer <JWT>

The JWT is generated using your Application ID and Private Key, both obtained when creating a Vonage Application in the Dashboard.

To generate a JWT, you’ll need your application ID and private key, both of which can be found in the Application settings in your Dashboard.

There are several ways to generate a new JWT:

• Using the JWT online generator.

• Using the Vonage CLI tool. The private key and an application ID must be provided:

Please note:

• If you are using one of the Vonage Server SDKs you do not have to generate a JWT separately, as all SDKs support the generation of JWT tokens.

• If you do not want to generate the JWT using an external tool or library, such as the Vonage SDKs, you can implement your own JWT generation. The how to generate a JWT blog post includes examples in JavaScript and Python that show how to generate a JWT without external dependencies.

Once generated, users should be able to use the token to access protected endpoints. This is typically done using the Authorization header using the Bearer schema:

Authorization: Bearer <JWT>

Setup Steps for Verify V2

1. Create a Vonage Application in the Vonage Dashboard.
2. Generate a public/private key pair — download and securely store the private key.
3. Enable Verify V2 for the application and configure the Status URL (webhook endpoint) to receive callbacks.
4. Generate a JWT signed with your Application ID and private key. You can use the JWT Generator, the Vonage CLI, or any Vonage SDK.
5. Include the JWT in all API requests using the Authorization: Bearer header.

Example Request

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

JWT tokens have a maximum time-to-live (TTL) of 24 hours. Make sure your integration refreshes tokens before expiry to avoid 401 Unauthorized errors.

What JWT Unlocks

• Summary callbacks — receive a full status report at the end of every verification request.
• Event callbacks — receive real-time events during the request (e.g., for Silent Auth and WhatsApp Interactive channels).
• ACL-scoped tokens — restrict token permissions to specific endpoints for enhanced security.
• Webhook configuration — configure verify_event_url and verify_status_url per Vonage Application.

Migrating Authentication from Verify Legacy (V1)

One of the key changes when migrating from Verify V1 to Verify V2 is how authentication is handled.

In Verify V1, authentication was handled by passing api_key and api_secret as query parameters or in the request body. This method is not supported in Verify V2.