Authentication

Vonage APIs support different authentication methods depending on which product you are using:

¹ Messages supports both JWT and Basic authentication, however basic authentication does not support webhooks or advanced features such as ACLs. For most use-cases we recommend JWT Authentication. See Messages API Authentication

² The JWT token generated serves as a bridge for generating a CAMARA access token, needed to access the Network APIs. The workflow varies based on whether the authentication is initiated from the frontend or the backend. Visit the Network API authentication guide to learn more.

³ Verify supports both JWT and Basic authentication, however basic authentication does not support webhooks or advanced features such as ACLs.

⁴ SIP Trunking uses Digest Authentication method with the API Key as user and API Secret as password.

Contents

In this document you can learn about authentication via the following means:

• API Key and Secret
  • Request Body
  • Query String
  • Basic Authentication
  • Secret Rotation
• JSON Web Tokens (JWT)

API Key and Secret

When you create a Vonage account, an API key and secret will be created for you. These are located in your account settings in the Vonage Dashboard. You should always keep these secure and never share these details: be careful when adding it to your codebase to make sure they are not shared with anyone who may use it maliciously. If you use message signatures, these are generated using the SIGNATURE_SECRET rather than the API_SECRET; both values can be found in your account settings.

Vonage APIs may require your API Key and Secret in a number of different ways.

Request Body

For POST requests to the SMS API, your API key and secret should be sent as part of the body of the request in the JSON object.

Query String

Your API key and secret should be included in the query parameters of requests you make to the Conversion, Number Insight or Developer API. The parameters are called API_KEY and API_SECRET respectively.

An example of authentication query parameters would be as follows:

?api_key=VONAGE_API_KEY&api_secret=VONAGE_API_SECRET

The request may also need other query parameters and these can be added in any order.

Basic Authentication

A number of newer Vonage APIs require authentication to be done using an API key and secret sent Base64 encoded in the Authorization header.

For these APIs, you send your API key and secret in the following way:

Authorization: Basic base64(API_KEY:API_SECRET)

If your API key were aaa012 and your API secret were abc123456789, you would concatenate the key and secret with a : (colon) symbol and then encode them using Base64 encoding to produce a value like this:

Authorization: Basic YWFhMDEyOmFiYzEyMzQ1Njc4OQ==

A website for generating Base64 encoded strings can be found here:

• General: Base64 Encode and Decode

Details on how to encode Base64 strings in a variety of programming languages can be found at the following websites:

• C#/.NET: How do I encode and decode a Base64 string? from StackOverflow
• Go: Base64 Encoding from Go By Example
• Java: Base64
• JavaScript: Base64 encoding and decoding from MDN web docs
• PHP: base64_encode
• Python: Base64
• Ruby: Base64
• Swift: Base64 Encode and Decode in Swift from iOS Developer Tips

Secret Rotation

It is possible to have two API secrets to be used against one API key at the same time. This way you can create a second API secret and test it before revoking the existing API secret in your production network. The API secret rotation procedure consists of the following steps:

1. Create a second API secret in your account settings or by using the secret rotation API.
2. Update one or more of your servers to use the newly created API secret for making calls to Vonage APIs
3. Test that there are no connectivity issues and roll out the API secret update across the remaining servers
4. Delete the replaced API secret

JSON Web Tokens

JSON Web Tokens (JWTs) are a compact, URL-safe means of representing claims to be transferred between two parties. For a full list of the APIs that use JWTs, please see the table above.

Header and Payload

JWTs consist of a Header and a Payload. The values for the Header are:

The values for the payload claim are:

Generating JWTs

Using the Vonage API online tool to generate a JWT

You can generate a JWT using our online tool.

Using the Vonage CLI to generate JWTs

The Vonage CLI provides a command for generating a JWT. The general syntax is:

An example of generating a JWT for an application is as follows:

Further information on the Vonage CLI can be found in its repository on GitHub.

Examples of using the Vonage libraries to generate JWTs can be found below. If you are not using a Vonage library you should refer to RFC 7519 to implement JWTs.

Vonage Client SDKs

The Vonage Client SDKs use JWTs for authentication when a user logs in. These JWTs are generated using the application ID and private key that is provided when a new application is created.

Claims

Using that private.key and the application ID, you can mint a new JWT. In order to log a user into a Vonage client, the JWT will need the following claims:

Sample JWT Payload

Once all the claims have been provided, the resulting claims should appear like so:

{
  "iat": 1532093588,
  "jti": "705b6f50-8c21-11e8-9bcb-595326422d60",
  "sub": "alice",
  "exp": "1532179987",
  "acl": {
    "paths": {
      "/*/rtc/**": {},
      "/*/users/**": {},
      "/*/conversations/**": {},
      "/*/sessions/**": {},
      "/*/devices/**": {},
      "/*/image/**": {},
      "/*/media/**": {},
      "/*/knocking/**": {},
      "/*/legs/**": {}
    }
  },
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Access Control List (ACL)

In the sample JWT request payload above, notice how the acl claim has a paths object. The path object contains a list of endpoints that correspond to certain permissions a user has when using the Client SDK.

Below is the list of endpoints you can grant a user access to:

You should provide the user you are generating with permissions to access only the relevant paths. For instance, if a user is not going to send images, you can create a JWT without including the /*/image/**or /*/media/** paths, similarly, you can grant a user permission by adding the required path.

To illustrate, if you add the /*/conversations/** path, the user will be able to create and manage conversations. Also, if this is the only ACL set, the user will only have access to the /conversations endpoint.

Granular ACL

Above, we looked at how to grant users access to endpoints. You may also limit or grant access based on sub-paths and HTTP methods.

Here is an example:

( ...:snippet is truncated )

The above ACL translates to the following permissions:

• "/path_1/*/path_2": {}: Allows access to the path /path_1/*/path_2 where * can be any sub-path. For example, /path_1/ABC/path_2 and /path_1/XYZ/path_2 will both be accessible.

• "/path/**": {"methods”: ["GET", "POST"]}: Allows only GET and POST calls through when accessing /path/ and any sub-path that come after that. For example, /path/sub_1/sub_2/sub_3 will still be accessible.

• "/path/**": {"methods”: []}: Calls made when using any HTTP method to endpoints starting with /path will not be accessible. For example, /path, /path/sub_1/, /path/sub_1/sub_2, and /path/sub_1/sub_2/sub_3 will all not be accessible.

Generating JWTs using the Vonage CLI

The Server SDKs contain methods for generating JWT tokens. You may however use the Vonage CLI to do this as well. This is particularly helpful during testing.

Using the Server SDKs

It is expected that the accompanying server for your Vonage application will generate JWTs for the Client SDK. Here are some examples using the Vonage Server SDKs:

const { tokenGenerate } = require('@vonage/jwt');

const privateKey = readFileSync('path/to/private.key');

const aclPaths = {
  "paths": {
    "/*/rtc/**": {},
    "/*/users/**": {},
    "/*/conversations/**": {},
    "/*/sessions/**": {},
    "/*/devices/**": {},
    "/*/image/**": {},
    "/*/media/**": {},
    "/*/knocking/**": {},
    "/*/legs/**": {}
  }
}

const token = tokenGenerate("aaaaaaaa-bbbb-cccc-dddd-0123456789ab", privateKey, {
      //expire in 24 hours
      exp: Math.round(new Date().getTime()/1000)+86400,
      sub: "alice",
      acl: aclPaths,
    });

val token : String = Jwt.builder()
    .applicationId("aaaaaaaa-bbbb-cccc-dddd-0123456789ab")
    .privateKeyPath("/path/to/private.key")
    .issuedAt(ZonedDateTime.now())
    .subject("alice")
    .addClaim("acl", mapOf(
        "paths" to mapOf(
            "/*/rtc/**" to mapOf(),
            "/*/users/**" to mapOf<String, Any>(),
            "/*/conversations/**" to mapOf(),
            "/*/sessions/**" to mapOf(),
            "/*/devices/**" to mapOf(),
            "/*/image/**" to mapOf(),
            "/*/media/**" to mapOf(),
            "/*/knocking/**" to mapOf(),
            "/*/legs/**" to mapOf()
        )
    ))
    .build()
    .generate()

String token = Jwt.builder()
    .applicationId("aaaaaaaa-bbbb-cccc-dddd-0123456789ab")
    .privateKeyPath(Paths.get("/path/to/private.key"))
    .subject("alice")
    .issuedAt(ZonedDateTime.now())
    .expiresAt(ZonedDateTime.now().plusMinutes(20))
    .addClaim("acl", Map.of(
        "paths", Map.of(
            "/*/users/**", Map.of(),
            "/*/conversations/**", Map.of(),
            "/*/sessions/**", Map.of(),
            "/*/devices/**", Map.of(),
            "/*/image/**", Map.of(),
            "/*/media/**", Map.of(),
            "/*/applications/**", Map.of(),
            "/*/push/**", Map.of(),
            "/*/knocking/**", Map.of(),
            "/*/legs/**", Map.of()
        )
    ))
    .build()
    .generate();

var payload = new Dictionary<string, object>
{
    {"sub", "alice"},
    {"exp", DateTimeOffset.UtcNow.AddDays(1).ToUnixTimeSeconds().ToString()},
    {
        "acl", new Dictionary<string, object>
        {
            ["paths"] = new Dictionary<string, object>
            {
                ["/*/users/**"] = new { },
            },
        }
    },
};

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var token = Jwt.CreateToken(credentials.ApplicationId, credentials.ApplicationKey, payload);

// Using the credentials instance
var result = tokenGenerator.GenerateToken(credentials, payload);

// Using ApplicationId and ApplicationKey values
var result = tokenGenerator.GenerateToken(credentials.ApplicationId, credentials.ApplicationKey, payload);

$keypair = new \Vonage\Client\Credentials\Keypair(
    file_get_contents('/path/to/private.key'),
    'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
);
$client = new \Vonage\Client($keypair);

$claims = [
    'acl' => [
        'paths' => [
            '/*/rtc/**' => (object) [],
            '/*/users/**' => (object) [],
            '/*/conversations/**' => (object) [],
            '/*/sessions/**' => (object) [],
            '/*/devices/**' => (object) [],
            '/*/image/**' => (object) [],
            '/*/media/**' => (object) [],
            '/*/knocking/**' => (object) [],
            '/*/legs/**' => (object) [],
        ]
    ]
];
$token = $client->generateJwt($claims);
$tokenString = $token->toString();

from vonage_jwt import JwtClient

jwt_client = JwtClient(application_id, private_key)

# The `claims` field is optional and can be omitted as defaults are set
claims = {'jti': 'test_jti', 'nbf': now + 100}
vonage_jwt = jwt_client.generate_application_jwt(claims)