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.

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

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

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.

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. Twilio limits the number of simultaneous devices you can create using a single client name.

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.

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.

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.