Menu

Expand
Rate this page:

User Identity & Access Tokens

Overview

An Access Token controls Participant identity and Room permissions in your Programmable Video application. Read below to learn more.

About Access Tokens

Access Tokens 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.

Access Token workflow

All Twilio Access Tokens must include the following information:

  • A Twilio Account SID, which is the public identifier of the Twilio account associated with the Access Token.
  • An API Key SID, which is the public identifier of the key used to sign the token.
  • An Identity grant, which sets the Twilio user identifier for the client holding the token.
  • The API Key Secret associated with the API Key SID is used to sign the Access Token and verify that it is associated with your Twilio account.

Programmable Video Access Tokens also include the following information:

  • A mandatory Video grant, which indicates the holder of the Access Token can access Programmable Video services.
  • Optionally, a Room grant (contained within the Video grant) for a specific Room name or SID, which indicates the holder of the Access Token may only connect to the indicated Room.

Access Tokens are based on the JSON Web Token standard (RFC 7519).

Limit Room Access

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:

  1. The Room's UniqueName.
  2. The Room's 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.

See below for working examples.

Note: If the Room Grant is scoped to a Room that has been created using the REST API with the EnableTurn property set to true, then media may be relayed over TURN servers, if required.

Time-To-Live (ttl)

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 14,400 seconds (4 hours).

Generating Access Tokens

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.

Use the Twilio CLI plugin

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 helper library

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.

        
        
        

        Access Token Server Sample Applications

        These sample applications demonstrate the generation of Access Tokens in different programming languages.

        Using Access Tokens

        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.

        Examples

        Below are examples for connecting to a Twilio Video Room using an Access Token.

        JavaScript

        const { connect } = require('twilio-video');
        
        connect('$TOKEN', { name:'my-new-room' }).then(room => {
          console.log(`Successfully joined a Room: ${room}`);
          room.on('participantConnected', participant => {
            console.log(`A remote Participant connected: ${participant}`);
          });
        }, error => {
          console.error(`Unable to connect to Room: ${error.message}`);
        });
        

        Android

        private Room.Listener roomListener() {
          return new Room.Listener() {
              @Override
              public void onConnected(Room room) {
                Log.d(TAG,"Connected to " + room.getName());
              }
          }
        }
        
        public void connectToRoom(String roomName) {
          ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)
            .roomName(roomName)
            .audioTracks(localAudioTracks)
            .videoTracks(localVideoTracks)
            .dataTracks(localDataTracks)
            .build();
          room = Video.connect(context, connectOptions, roomListener);
        }
        

        iOS

        @IBAction func createARoom(sender: AnyObject) {
            let connectOptions = ConnectOptions(token: accessToken) { (builder) in
                builder.roomName = "my-room"
            }
            room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)
        }
        
        // MARK: RoomDelegate
        
        func roomDidConnect(room: Room) {
            print("Did connect to Room")
        
            if let localParticipant = room.localParticipant {
                print("Local identity \(localParticipant.identity)")
        
                // Set the delegate of the local particiant to receive callbacks
                localParticipant.delegate = self
            }
        }
        
        Kedar Toraskar Manjesh Malavalli Luis Lopez Chris Eagleston Aymen Naim Sarah Stringer
        Rate this page:

        Need some help?

        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more