Authentication

Overview

JSON Web Tokens, or JWTS, are a compact and self-contained way for securely transmitting information between parties, using a JSON object to provide structure. This information can be verified and strusted as it can digitally signed.

JWTs are an open standard, formally defined in RFC 7519, and is further extended in a variety of other RFCs. This provides a robust base in which to pass information between a client and a server.

A key characteristic of JWTs is their compact size. This makes them suitable for transmitting within URLs, POST parameters, or HTTP Headers. The JWT itself is also encoded as a Base-64 string, making it easy to inject into applications from sources like command line applications, environment files, and over the internet.

Vonage primarily uses JWTs for authentication to a variety of APIs on both the front-end and the back-end. The Vonage In-App Chat and Voice Client SDK, and Vonage Video API both use JSON Web Tokens (JWT) for authentication, and the Vonage Video API uses JWTs to pass additional client configuration for video clients.

These tokens are then signed cryptographically using a private key that is associated with a Vonage Application. This signing process provides a secure way to validate that tokens being used are from your application.

Using JWTs

For Vonage Video, JWTs are used in two places:

REST API calls
Video Client Connections

While both uses use JWTs, the information contained in each one is different.

REST API calls

The Vonage Video API uses Bearer Authentication. While Bearer Authentication is an extension of the OAuth 2.0 authentication scheme, Vonage uses the OAuth 2.0 generation non-interactive method for creating a Bearer Token using the JWT structure and your private key.

When sending a request to Vonage Video REST API endpoint, You will need to use the Authorization header in the following format:

Authorization: Bearer <JWT>

For information about what information is needed for a REST API JWT token, see the JWT Structure section below. All REST API call JWT tokens are considered "root" tokens, which means they have full access to the REST API. These tokens should NEVER be shared with a front-end client.

While you can generate a JWT token yourself, we do have helpers built into the SDKs as well as JWT-specific wrappers that are designed to work with Vonage APIs. The Server SDKs automatically generate JWTs for you for each request, but if you need to generate a JWT for either a feature that is not in the SDKs or to test with beta features, we provide JWT generators independent from the SDKs as well:

Version 3 of the Vonage Node Server SDK includes a package for generating JWT tokens. It can also generate a JWT using the appropriate claims.

The Vonage .NET SDK can be used to generate a signed JWT with claims.

As an example, let's assume we want to add the following claims in the JWT:

There are several ways to generate a JWT.

You can either use the static method CreateToken on the Jwt class:

Or use the method GenerateToken on a Jwt instance:

Client SDK Connection Tokens

Client applications using the Video API client SDKs require connection tokens to authenticate when connecting to a session. This allows a signed and secure way to transmit the connection information for a specific user without needing to provide full access to the API. Client JWTs are locked down to a specific application, have strict scope in what they can access, and are only valid for specific routes and HTTP methods. Video Client SDK tokens have additional information to make it easy to pass information to the front-end client.

Client Connection Tokens are generated on the server-side portion of your application, and then passed up to the client. This allows the token to be securely signed using the Vonage Application private key. To make this process easier, creating Client Connection tokens is built into the SDKs, and we provide wrappers:

As with the server-side SDKs, you can create client tokens yourself if you have a specific need to do so. Consult the JWT Structure section for information about what additional information a client token requies. Each SDK does contain a helper method to create client tokens for you:

JWTs creation

Vonage has a variety of ways that you can create JWTs, which can be useful during testing and debugging.

Using the Vonage Server SDK

We recommend using the Server SDKs to generate client-side token. This provides some additional safeguards and defaults for the JWTs, and reduces creating the tokens down to one call. REST API calls automatically generate JWTs per request, so there is no need for a user to create a JWT to access the REST API.

Using the Vonage API online tool

If you want to generate a server-side JWT for testing purposes, you can generate a JWT using our online tool.

Enter your private key and the application ID for your video application. For video server-side JWT tokens, you will need to leave the "Sub" and "ACL" options empty. The resulting JWT can be used in cURL commands or API clients to test REST API calls.

Currently you cannot use this tool to create client connection tokens.

Using the Vonage CLI

The Vonage CLI provides a command for generating a JWT. The CLI allows you to set all the additional properties/claims that are needed for a JWT, and can be used programmatically to create JWTs.

To generate a JWT for use with the REST API, you can use the following:

# A command with parameters vonage jwt create \ --app-id='00000000-0000-0000-0000-000000000000' \ --private-key=./private.key # Will produce a token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzYyODE5NDYsImp0aSI6IjBmZjcwZDNmLTAzN2EtNGY4MC04ODZjLWI3MmM3MmQyMWNmMiIsImlhdCI6MTczNjI4MTA0NiwiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.gA7jClpqaZ2OoS0iri-zGCbda4jO7C0M8mka0EnSyjlds1EeY8fNoBEx3FTXHfkkzzrj0TskrWc_dcs1wuM8Kx55c5rLQ7taVpDAYopKSc_CeeOaad8S6aWnRkTUTNeduO4aIn-0CbyRTluBYsH1RBqYBQvobuQIDEwbFw8xBgx0UfREMMN6DAWknR57eiVXN9x_oD6CGQJ1yV3025nGboeMsP9YgX4Nwc-rE2r8c1ZGwCLO81x8i19Qil3Nwu5q1nzouyavQjIw00B_TZkushnI1ufdi_GNqk-h5q2HvGkg7Pj9bVkZHFdVTO8im03JYNyJmcV83vnpjOLuCFRzxQ

The private key in question is generated from the application dashboard or from the usage of vonage apps create terminal command. You can save this information for the CLI by running vonage auth set command. The contents of the private key will then be saved in either the .vonagerc or $HOME/.vonage/config.json file.

You may use the Vonage CLI to create client connection tokens as well. You need to pass the additional client claims as part of the command:

# A command with parameters vonage jwt create \ --app-id='00000000-0000-0000-0000-000000000000' \ --private-key=./private.key \ --sub='Alice' \ --acl='{"paths":{"/*/sessions/**":{}}}' # Will produce a token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ

Using Other Libraries

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 your own JWT solution. If you don't want to do that, JWT.io has a selection of libraries for generating JWTs in multiple languages.

JWT Structure

JWTs contain information that needs to be shared between a client (either a video session client or a backend server) with the Vonage APIs themselves. This includes information that is needed to help work with the REST API endpoints and client servers, as well as information about the validity of the token itself.

All JWTs that interact with the Vonage Video API have the following basic Claims, or informational keys:

Claim	Type	Required	Description
`application_id`	String	True	The ID of the Vonage Application you created.
`iat`	Number (Unix epoch time)	True	"Issued at time" This is the time the JWT was issued.
`jti`	String	True	"JWT ID", a unique identifier for this JWT.
`exp`	Number (Unix epoch time)	False	"Expiration time". This is the time in the future that the JWT will expire.

If the exp claim is not provided, then the JWT will expire by default in 15 minutes. The max expiration time for a JWT is 24 hours. JWTs should typically be short-lived, as it is trivial to create a new JWT and some JWTs can have multiple far-reaching permissions.

Sample Token for REST API calls

Server-side tokens used for making REST API calls only need these claims.

Additional Claims for Client Connection Tokens

To generate a JWT for use as a connection token for a client using one of the Video Client SDKs, you need to supply additional claims to the ones described above.

Claim	Type	Required	Description
`sub`	String	True	The subject. Set this to to `video`.
`acl`	String	True	For details, see the Access Control List (ACL).
`session_id`	String	True	The session ID of the video session.
`scope`	String	True	The scope of the token. Set this to `session.connect`.
`role`	String	True	The role of the token. It can be a range of string values depending on what permissions you want to the client connecting to the session.
`data`	String	False	Custom metadata you can add to describe the client connecting to the session. This is limited to 1000 characters.
`initial_layout_class_list`	String	False	This lets you optionally specify the initial layout class list for archives and live streaming broadcasts for streams published by the client.

Sample Video Client Connect Token Payload

Access Control List (ACL)

Client Connection tokens are limited by the acl claim of the token. This ACL is a list of paths that the token is allowed to access. Our API will reject any token, even a successfully signed token, if it attempts to call a route that is not outlined in acl.paths.

For the purpose of the Video API, you only need to grant a user an acces to /*/session/** endpoint, allowing them to join a video session. There are more endpoints available, but not related to Video API.

Note that JWT tokens being used to call the REST API do not require an acl claim.