Twilio Client: Capability Tokens

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.

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-python][python] module to configure and generate capability tokens.

Allow Incoming Connections

To allow incoming connections 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. In twilio.js an incoming connection attempt triggers the Twilio.Device.incoming event handler.

from twilio.jwt.client import ClientCapabilityToken

account_sid = 'ACXXXXXXXXXXXXXXX'
auth_token = 'secret'

capability = ClientCapabilityToken(account_sid, auth_token)
capability.allow_client_incoming('tommy')
print(capability.to_jwt())

A device configured with this token will receive incoming connections anytime someone attempts to connect to tommy, 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 the <Queue> noun of the <Dial> verb.

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.

from twilio.jwt.client import ClientCapabilityToken

account_sid = 'ACXXXXXXXXXXXXXXX'
auth_token = 'secret'
application_sid = 'AP123123'

capability = ClientCapabilityToken(account_sid, auth_token)
capability.allow_client_outgoing(application_sid)
print(capability.to_jwt())

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

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:

from twilio.jwt.client import ClientCapabilityToken

account_sid = 'ACXXXXXXXXXXXXXXX'
auth_token = 'secret'
application_sid = 'AP123123'

capability = ClientCapabilityToken(account_sid, auth_token)
capability.allow_client_incoming('tommy')
capability.allow_client_outgoing(application_sid)
print(capability.to_jwt())

Security

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 Time To Live, ttl, argument expects time in seconds.

capability = ClientCapabilityToken(account_sid, auth_token, ttl=600)
print(capability.to_jwt())