REST API: Network Traversal Service Tokens

Network Traversal Service Tokens are ephemeral credentials that let you access TURN resources from WebRTC and VoIP clients. They are a secure way to create communication sessions with web browsers or mobile apps without exposing credentials in a client-side environment. All tokens have a limited lifetime to protect you from abuse. The lifetime is configurable up to 24 hours (which is also the default value) but you should make it as short as possible for your application.

Token List Resource

Resource URI

1/2010-04-01/Accounts/{AccountSid}/Tokens
2

Resource Properties

A Token instance resource has the following properties

Property	Description
Username	The temporary username that uniquely identifies a Token.
Password	The temporary password that the username will use when authenticating with Twilio.
Ttl	The duration in seconds for which the username and password are valid, the default value is 86,400 (24 hours)
AccountSid	The unique id of the Account that created this Token.
IceServers	An array representing the ephemeral credentials and the STUN and TURN server URIs.
DateCreated	The date that this resource was created, given in RFC 2822 format.
DateUpdated	The date that this resource was last updated, given in RFC 2822 format.

HTTP GET

Not Supported

HTTP POST

You can create a new Token resource by POSTing to the Tokens list resource. Since the purpose of tokens is to provide short-lived credentials, usernames and passwords are always auto-generated and not intended to be stored long term.

Optional Parameters

You may POST the following parameters:

Parameter	Description
Ttl	The duration in seconds for which the generated credentials are valid, the default value is 86400 (24 hours).

Examples

Create a Token Resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createToken() {
11  const token = await client.tokens.create();
12
13  console.log(token.accountSid);
14}
15
16createToken();

Response

1{
2  "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
3  "ice_servers": [
4    {
5      "urls": "stun:global.stun.twilio.com:3478"
6    },
7    {
8      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
9      "credential": "tE2DajzSJwnsSbc123",
10      "urls": "turn:global.turn.twilio.com:3478?transport=udp"
11    },
12    {
13      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
14      "credential": "tE2DajzSJwnsSbc123",
15      "urls": "turn:global.turn.twilio.com:3478?transport=tcp"
16    },
17    {
18      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
19      "credential": "tE2DajzSJwnsSbc123",
20      "urls": "turn:global.turn.twilio.com:443?transport=tcp"
21    }
22  ],
23  "date_updated": "Fri, 01 May 2020 01:42:57 +0000",
24  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
25  "ttl": "86400",
26  "date_created": "Fri, 01 May 2020 01:42:57 +0000",
27  "password": "tE2DajzSJwnsSbc123"
28}

Create Token Resource during 1 hour

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createToken() {
11  const token = await client.tokens.create({ ttl: 3600 });
12
13  console.log(token.accountSid);
14}
15
16createToken();

Response

1{
2  "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
3  "ice_servers": [
4    {
5      "urls": "stun:global.stun.twilio.com:3478"
6    },
7    {
8      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
9      "credential": "tE2DajzSJwnsSbc123",
10      "urls": "turn:global.turn.twilio.com:3478?transport=udp"
11    },
12    {
13      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
14      "credential": "tE2DajzSJwnsSbc123",
15      "urls": "turn:global.turn.twilio.com:3478?transport=tcp"
16    },
17    {
18      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
19      "credential": "tE2DajzSJwnsSbc123",
20      "urls": "turn:global.turn.twilio.com:443?transport=tcp"
21    }
22  ],
23  "date_updated": "Fri, 01 May 2020 01:42:57 +0000",
24  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
25  "ttl": 3600,
26  "date_created": "Fri, 01 May 2020 01:42:57 +0000",
27  "password": "tE2DajzSJwnsSbc123"
28}

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Global Low Latency (GLL) and Region Pinning

The Network Traversal Service API provides Credentials and URIs that allow access to Twilio STUN and TURN servers. These URIs are global in nature. When your WebRTC client uses these URIs they will resolve to one of the Twilio Regions depending on which one has the lowest latency at the time of use. If you wish to pin all STUN or TURN requests to a specific Twilio region then the URIs returned in the Token need to be adjusted. Each URI begins with the prefix global. This prefix should to be replaced by the Twilio region/edge location name that you wish to pin to, e.g. frankfurt for the Twilio region/edge in Germany.

Below is an example of the IceServers array that is pinned to the frankfurt region/edge.

1  "ice_servers": [
2    {
3      "urls": "stun:frankfurt.stun.twilio.com:3478"
4    },
5    {
6      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
7      "credential": "tE2DajzSJwnsSbc123",
8      "urls": "turn:frankfurt.turn.twilio.com:3478?transport=udp"
9    },
10    {
11      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
12      "credential": "tE2DajzSJwnsSbc123",
13      "urls": "turn:frankfurt.turn.twilio.com:3478?transport=tcp"
14    },
15    {
16      "username": "dc2d2894d5a9023620c467b0e71cfa6a35457e6679785ed6ae9856fe5bdfa269",
17      "credential": "tE2DajzSJwnsSbc123",
18      "urls": "turn:frankfurt.turn.twilio.com:443?transport=tcp"
19    }
20  ],