Rate this page:

Capability Tokens for Twilio Client

Capability Tokens have been deprecated and this tutorial no longer uses the correct authentication methods for Twilio Client. Please use Access Tokens for all future use cases.

Twilio Client relies on capability tokens to sign communications from devices to Twilio. These tokens are a secure way of setting up your device to access various features of Twilio. Capability tokens allow you to add Twilio capabilities to web and mobile applications without exposing your AuthToken in JavaScript or any other client-side environment.

You create a token on your server and specify what capabilities you'd like your device to have. All tokens have a limited lifetime to protect you from abuse. The lifetime is configurable up to 24 hours, but you should make it as short as possible for your application.

The client identifier currently may only contain alpha-numeric and underscore characters.

Creating Tokens

Twilio capability tokens are based on the JSON Web Token standard. However, if you're using one of Twilio's official helper libraries you can use its token-generation functionality to create tokens easily without having to know the details of how they are constructed. Consult the documentation of the library you're using for more information.

The following examples use the Twilio helper libraries to configure and generate capability tokens.

Allow Incoming Connections

To allow Twilio to connect to a device you need to give the device a client name. A connection attempt to this client name will trigger an incoming event in your environment. You provide the client name to the incoming capability when generating the token, as shown below:


        A device configured with this token will receive incoming connections anytime someone attempts to connect to joey, either using the <Client> noun of the <Dial> verb or the REST API.

        If you have multiple devices configured to use the same client name, each device will receive the incoming connection; however, only one device can accept the connection. In a contact center or other inbound calling scenario, it is highly recommended that you utilize one unique client name for each device (agent). To distribute calls across multiple agents, use Twilio TaskRouter. Twilio limits the number of simultaneous devices you can create using a single client name.

        Allow Outgoing Connections

        To make an outgoing connection from a device, you'll need to configure a capability token with the SID of a Twilio Application so that Twilio will know what VoiceUrl to use to handle the connection. A Twilio Application is just a named collection of URLs responsible for returning TwiML instructions to control phone calls and SMS.


              A device configured with this token will be able to make outgoing connections to the VoiceUrl of the Twilio Application identified by APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

              Multiple Capabilities

              It is perfectly valid to configure a device with multiple capabilities. For instance, to set up a client to receive incoming connections as well as initiate outgoing connections, you would create a token with both capabilities and initiate your device with it:



                    Security is very important to us and we have made sure that you as the developer are in control. You decide what access rights to grant a Twilio Client device using capability tokens generated with one of our helper libraries. We ensure that any tampering with the token parameters is detected and the appropriate actions are taken.

                    Token Expiration

                    By default all tokens generated with the Twilio helper libraries expire after one hour. But you should configure this expiration to be as short as possible for your application. For instance, if you have an outgoing-only application, you could set a token's lifetime to be just long enough to establish each outgoing connection (say 5 seconds), and generate a new token each time a user attempts a new connection.

                    If the token expires while the device has an active connection, the connection will not be terminated, but the device will need to be re-initialized with a valid token before attempting or receiving another connection.

                    Here, we generate a token that's only valid for ten minutes. The expires argument expects time in seconds.

                          David Prothero Eliecer Hernandez Kat King 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 Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.


                                Thank you for your feedback!

                                Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                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