This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.
This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.
An Access Token controls Participant identity and Room permissions in your Programmable Video application. Read below to learn more.
Access Tokens are JSON Web Tokens (JWTs). They are short-lived credentials that are signed with a Twilio API Key Secret and contain grants that govern the actions the client holding the token is permitted to perform.
End-users require an Access Token to join a Twilio Video Room. Below is the general workflow that your application will need to generate Access Tokens and allow end-users to connect to Twilio Video Rooms.
All Twilio Access Tokens must include the following information:
The API Key you use to create Access Tokens must be in the United States (US1) region. Access Tokens that are generated with API Keys in other regions outside of US1 will not work and will not connect to Video Rooms.
You can select the key's region when you create the API key.
To see a list of your API keys in the United States (US1) region, select that region from the dropdown in the top right side of the page in the Auth Token and API Keys section of the Twilio Console.
Programmable Video Access Tokens also include the following information:
The Room grant allows you to scope a Participant's access to a single Room. When a Participant connects with a token that contains a Room grant, the value is compared against:
UniqueName
.
Sid
.
For example, if the Access Token contains a Room grant for DailyStandup
, the client holding this Access Token will only be allowed to connect to the Room with the UniqueName
property DailyStandup
.
Access Tokens must be valid while joining a Room and when reconnecting to a Room due to network disruption or handoff. We recommend that you set the ttl
to the maximum allowed session length, which is currently 86,400 seconds (24 hours).
You can generate Access Tokens using either a Twilio CLI plugin or a Twilio Helper Library. The Twilio CLI Plugin is a useful tool for creating individual Access Tokens for testing or getting started with Twilio Video. You should use the Twilio Helper Libraries to generate Access Tokens in your application's server.
The Twilio CLI has a plugin for generating Access Tokens from the command line. This can be useful for testing Access Tokens when you are starting to develop your application.
First, you will need to install the Twilio CLI and log in to your Twilio account from the command line; see the CLI Quickstart for instructions. Then, you can install the plugin with the following command:
twilio plugins:install @twilio-labs/plugin-token
To generate an Access Token, run the following command. --identity
is a required argument and should be a string that represents the user identity for this Access Token.
twilio token:video --identity=<identity>
You can add other arguments to the command, such as TTL and room name. To see the list of options, use the --help
flag:
twilio token:video --help
Use a Twilio server-side helper library to generate an Access Token in your back-end server. See below for examples of creating an Access Token for a particular user to enter a specific Video Room.
1const AccessToken = require('twilio').jwt.AccessToken;2const VideoGrant = AccessToken.VideoGrant;34// Used when generating any kind of tokens5// To set up environmental variables, see http://twil.io/secure6const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;7const twilioApiKey = process.env.TWILIO_API_KEY;8const twilioApiSecret = process.env.TWILIO_API_SECRET;910const identity = 'user';1112// Create Video Grant13const videoGrant = new VideoGrant({14room: 'cool room',15});1617// Create an access token which we will sign and return to the client,18// containing the grant we just created19const token = new AccessToken(20twilioAccountSid,21twilioApiKey,22twilioApiSecret,23{identity: identity}24);25token.addGrant(videoGrant);2627// Serialize the token to a JWT string28console.log(token.toJwt());
These sample applications demonstrate the generation of Access Tokens in different programming languages.
If you do not want to host your own server to create Access Tokens, you can use a serverless Twilio Function to create an Access Token server hosted in Twilio's cloud. See an example of how to generate Access Tokens without a server or an example of creating a serverless video application in the Twilio Blog.
Using a Twilio helper library is the easiest way to create an Access Token. Twilio's helper libraries have code that generate the Access Tokens in the correct format. However, it is possible to write your own code to do this if you are not using a helper library.
Access Tokens are standard JSON Web Tokens that use the HS256 signing algorithm. The signing key is your API Key Secret. You can review all the elements included in the Access Token in the Access Token API documentation.
To ensure that you are creating a token with the correct format and grants, you can generate a single token using the Twilio CLI or Twilio helper libraries and decode its payload to verify you are generating your own tokens with the same format. You can decode a JWT token at https://jwt.io.
You can also use the source code for Twilio's helper libraries as a reference to see how a particular library generates Access Tokens.
You can find the code for each helper library in GitHub:
After you have generated an Access Token on the server-side of your application (or generated an Access Token via the Twilio CLI), you can use it to connect to a Programmable Video Room in a client-side application. You can learn more about how to connect to a Video Room using an Access Token in the Getting Started guides for JavaScript, Android, and iOS.
Below are examples for connecting to a Twilio Video Room using an Access Token.
1const { connect } = require('twilio-video');23connect('$TOKEN', { name:'my-new-room' }).then(room => {4console.log(`Successfully joined a Room: ${room}`);5room.on('participantConnected', participant => {6console.log(`A remote Participant connected: ${participant}`);7});8}, error => {9console.error(`Unable to connect to Room: ${error.message}`);10});
1private Room.Listener roomListener() {2return new Room.Listener() {3@Override4public void onConnected(Room room) {5Log.d(TAG,"Connected to " + room.getName());6}7}8}910public void connectToRoom(String roomName) {11ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)12.roomName(roomName)13.audioTracks(localAudioTracks)14.videoTracks(localVideoTracks)15.dataTracks(localDataTracks)16.build();17room = Video.connect(context, connectOptions, roomListener);18}
1@IBAction func createARoom(sender: AnyObject) {2let connectOptions = ConnectOptions(token: accessToken) { (builder) in3builder.roomName = "my-room"4}5room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)6}78// MARK: RoomDelegate910func roomDidConnect(room: Room) {11print("Did connect to Room")1213if let localParticipant = room.localParticipant {14print("Local identity \(localParticipant.identity)")1516// Set the delegate of the local particiant to receive callbacks17localParticipant.delegate = self18}19}