Twilio Client: Capability Tokens
Capability Tokens have been deprecated. Please use Access Tokens for all future use cases.
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.
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
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
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
Twilio limits the number of simultaneous devices you can create using a single client name to ten; when the 11th instance of the same client name is registered the oldest registration will be dropped.
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
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
VoiceUrl of the Twilio Application identified by
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 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.
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,
argument expects time in seconds.
capability = ClientCapabilityToken(account_sid, auth_token, ttl=600) print(capability.to_jwt())
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.