Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Access Tokens


Access Tokens are short-lived tokens that you use to authenticate Twilio Client SDKs like Voice, Conversations, Sync and Video.

You create them on your server to verify a user's identity and grant access to client API features. All tokens have a limited lifetime, configurable for up to 24 hours. However, a best practice is to generate Access Tokens for the shortest amount of time feasible for your application.


Contents

contents page anchor

Anatomy of an Access Token

token-anatomy page anchor

Each Access Token is a JSON Web Token(link takes you to an external page) (JWT), an encoded JSON object with three parts: the header, the payload, and the signature. The following is an example Access Token generated for Conversations.


_10
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImN0eSI6InR3aWxpby1mcGE7dj0xIn0.eyJqdGkiOiJTS3h4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4LTE0NTA0NzExNDciLCJpc3MiOiJTS3h4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4Iiwic3ViIjoiQUN4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eCIsIm5iZiI6MTQ1MDQ3MTE0NywiZXhwIjoxNDUwNDc0NzQ3LCJncmFudHMiOnsiaWRlbnRpdHkiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaXBfbWVzc2FnaW5nIjp7InNlcnZpY2Vfc2lkIjoiSVN4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eCIsImVuZHBvaW50X2lkIjoiSGlwRmxvd1NsYWNrRG9ja1JDOnVzZXJAZXhhbXBsZS5jb206c29tZWlvc2RldmljZSJ9fX0.IHx8KeH1acIfwnd8EIin3QBGPbfnF-yVnSFp5NpQJi0

If you inspect it with the debugger at jwt.io(link takes you to an external page), you can further explore its content.

Header

jwt-header page anchor

_10
{
_10
"typ": "JWT",
_10
"alg": "HS256",
_10
"cty": "twilio-fpa;v=1"
_10
}

The header section encodes the format of the token:

  • typ is the type of token. Its value must be "JWT" .
  • alg is the algorithm used to encode the token. Its value must be "HS256" .
  • cty is the content type and encodes the version of the Access Token. Its value must be "twilio-fpa;v=1" .

_14
{
_14
"jti": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-1450471147",
_14
"iss": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
_14
"sub": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
_14
"iat": 1450471147,
_14
"nbf": 1450471147,
_14
"exp": 1450474747,
_14
"grants": {
_14
"identity": "user_name",
_14
"chat": {
_14
"service_sid": "ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
_14
}
_14
}
_14
}

The payload section describes the authorization granted:

  • jti is a unique identifier for the token. Your application can choose this identifier. The default helper library implementation includes the SID of the API key used to generate the token and a unique random string.
  • iss is the issuer — the API key containing the secret used to sign the token.
  • sub is the SID of the Twilio Account to which access is scoped.
  • iat is the timestamp at which the token was issued.
  • nbf is an optional timestamp, before which the token will NOT be accepted.
  • exp is the timestamp at which the token will expire. Tokens have a maximum age of 24 hours.
  • grants is the list of permissions that the token grants. Grant properties and values will depend on the Twilio product and the needs of your specific use case. (See the Grants section below for more information.)

The signature section is a signed hash that serves to prove the authenticity of the token. It is the result of hashing the JWT header and payload together with your API key secret, which should only be known to your application and Twilio.


Create Access Tokens

creating-tokens page anchor

Twilio Access Tokens are based on the JSON Web Token(link takes you to an external page) standard.

You can use one of Twilio's Helper Libraries to create Access Tokens quickly and programmatically.

Step 1: Find your Account SID

step-1-account-sid page anchor

Every Access Token requires your Account SID, which you can find in your Twilio Console(link takes you to an external page). This is how the AccessToken will tie a user's activity to a specific Twilio account.

Step 2: Create an API Key and Secret

step-2-api-key page anchor

Next, you need to create an API key. You can create API keys from the Twilio Console(link takes you to an external page) or with the REST API.

Note: You can create Access Tokens using Main and Standard API Keys. Creating Access Tokens is not yet supported with Restricted API Keys.

(warning)

Warning

If you are creating a key to use with Twilio Video, you must create it in the US1 Region. Learn more in the Twilio Video documentation.

When you create the API key, you'll be shown the key's secret, which is used to sign the Access Token. For security, you will only be shown the secret at this time, so you need to store it with the key's SID in a secure location for the next step.

Step 3: Generate an Access Token

step-3-generate-token page anchor

Now use the information gathered in steps 1 and 2 to generate an Access Token using a Twilio Helper Library.

When creating an Access Token, you must provide:

  • Your Twilio Account SID
  • The API key SID and API key secret from Step 2

You can also optionally provide any of the following JWT configuration values.

ParameterDescriptionExample
identityThe identity to associate with the Access Token. Typically, this will be a username in your system. Voice tokens may only contain alpha-numeric and underscore characters.user_name
ttlTime to live for the token, in seconds.3600
nbfToken not before time, or the time before which the token will NOT be accepted. Values are in Epoch time.1615404972
regionThe intended Twilio Region for the token. Currently only supported for Voice tokens.us1

Each Twilio product will also require at least one "grant", which will provide product-specific abilities to the user associated with an Access Token.

(warning)

Warning

Programmable Voice access tokens limit the number of concurrent sessions for a given identity to ten. When the 11th instance of the identity is registered the oldest registration is removed.

Use a Helper Library to create Access Tokens

use-a-helper-library-to-create-access-tokens page anchor

Below are code samples for creating Access Tokens with Twilio Helper Libraries. Click on a product below to jump to the related code samples.

Create an Access Token for Conversations

create-an-access-token-for-conversations page anchor

The Conversations SDK requires each Access Token to contain a ChatGrant. Each ChatGrant must contain the SID for your Conversation Service. Each Access Token will also contain an identity grant that associates an Access Token with a specific user.

Create an Access Token for Conversations

create-an-access-token-for-conversations-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby

_32
const AccessToken = require('twilio').jwt.AccessToken;
_32
const ChatGrant = AccessToken.ChatGrant;
_32
_32
// Used when generating any kind of tokens
_32
// To set up environmental variables, see http://twil.io/secure
_32
const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;
_32
const twilioApiKey = process.env.TWILIO_API_KEY;
_32
const twilioApiSecret = process.env.TWILIO_API_SECRET;
_32
_32
// Used specifically for creating Chat tokens
_32
const serviceSid = process.env.TWILIO_CHAT_SERVICE_SID;
_32
const identity = 'user@example.com';
_32
_32
// Create a "grant" which enables a client to use Chat as a given user,
_32
// on a given device
_32
const chatGrant = new ChatGrant({
_32
serviceSid: serviceSid,
_32
});
_32
_32
// Create an access token which we will sign and return to the client,
_32
// containing the grant we just created
_32
const token = new AccessToken(
_32
twilioAccountSid,
_32
twilioApiKey,
_32
twilioApiSecret,
_32
{identity: identity}
_32
);
_32
_32
token.addGrant(chatGrant);
_32
_32
// Serialize the token to a JWT string
_32
console.log(token.toJwt());

Create an Access Token for Voice

create-an-access-token-for-voice page anchor

Create an Access Token for the Voice SDKs

create-an-access-token-for-the-voice-sdks page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby

_31
const AccessToken = require('twilio').jwt.AccessToken;
_31
const VoiceGrant = AccessToken.VoiceGrant;
_31
_31
// Used when generating any kind of tokens
_31
// To set up environmental variables, see http://twil.io/secure
_31
const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;
_31
const twilioApiKey = process.env.TWILIO_API_KEY;
_31
const twilioApiSecret = process.env.TWILIO_API_SECRET;
_31
_31
// Used specifically for creating Voice tokens
_31
const outgoingApplicationSid = 'APxxxxxxxxxxxxx';
_31
const identity = 'user';
_31
_31
// Create a "grant" which enables a client to use Voice as a given user
_31
const voiceGrant = new VoiceGrant({
_31
outgoingApplicationSid: outgoingApplicationSid,
_31
incomingAllow: true, // Optional: add to allow incoming calls
_31
});
_31
_31
// Create an access token which we will sign and return to the client,
_31
// containing the grant we just created
_31
const token = new AccessToken(
_31
twilioAccountSid,
_31
twilioApiKey,
_31
twilioApiSecret,
_31
{identity: identity}
_31
);
_31
token.addGrant(voiceGrant);
_31
_31
// Serialize the token to a JWT string
_31
console.log(token.toJwt());

The Voice SDKs require each Access Token to contain an identity grant and a VoiceGrant. The identity grant is what associates an Access Token with a specific user.

Each VoiceGrant contains the following parameters:

ParameterTypeDescription
incomingAllowbooleanIndicates whether or not the endpoint associated with this Access Token is allowed to receive incoming calls as the identity included in the Access Token
outgoingApplicationSidstringThe SID of the TwiML App that Twilio will look to when making outgoing calls. (Note: This is required for using any of the Voice SDKs.)
outgoingApplicationParamsobjectRequest parameters to send to the TwiML Application for outgoing calls
pushCredentialSidstringThe SID of the Push Credential to use when registering to receive incoming call notifications (Mobile SDKs only)

The payload of a decoded Voice AccessToken will look something like the following:


_19
{
_19
"jti": "SKxxxx...-1643993631",
_19
"grants": {
_19
"identity": "alice",
_19
"voice": {
_19
"incoming": {
_19
"allow": true
_19
},
_19
"outgoing": {
_19
"application_sid": "APxxxx..."
_19
},
_19
"push_credential_sid": "CRxxxx..."
_19
}
_19
},
_19
"iat": 1643993631,
_19
"exp": 1643997231,
_19
"iss": "SKxxxx...",
_19
"sub": "ACxxxx..."
_19
}

Create an Access Token for Video

create-an-access-token-for-video page anchor
(warning)

Warning

The API Key you use to create an Access Token for Twilio Video must be in the US1 region.

The Video SDKs require each Access Token to contain an identity grant and a VideoGrant.

The identity grant is what associates an Access Token with a specific user.

Each VideoGrant contains an optional room parameter for a specific Room name or SID, which indicates the holder of the Access Token may only connect to the indicated Room.

Learn more about Video Access Tokens on the User Identity & Access Tokens page.

Create an Access Token for Video

create-an-access-token-for-video-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby

_28
const AccessToken = require('twilio').jwt.AccessToken;
_28
const VideoGrant = AccessToken.VideoGrant;
_28
_28
// Used when generating any kind of tokens
_28
// To set up environmental variables, see http://twil.io/secure
_28
const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;
_28
const twilioApiKey = process.env.TWILIO_API_KEY;
_28
const twilioApiSecret = process.env.TWILIO_API_SECRET;
_28
_28
const identity = 'user';
_28
_28
// Create Video Grant
_28
const videoGrant = new VideoGrant({
_28
room: 'cool room',
_28
});
_28
_28
// Create an access token which we will sign and return to the client,
_28
// containing the grant we just created
_28
const token = new AccessToken(
_28
twilioAccountSid,
_28
twilioApiKey,
_28
twilioApiSecret,
_28
{identity: identity}
_28
);
_28
token.addGrant(videoGrant);
_28
_28
// Serialize the token to a JWT string
_28
console.log(token.toJwt());

Create an Access Token for Sync

create-an-access-token-for-sync page anchor

Sync requires your Access Token to contain an identity grant and a SyncGrant. The identity grant is what associates an Access Token with a specific user.

The SyncGrant requires a serviceSid parameter containing the SID for your Sync Service.

Learn more about Sync Access Tokens on the Issuing Sync Tokens page.

Create an Access Token for Sync

create-an-access-token-for-sync-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby

_30
const AccessToken = require('twilio').jwt.AccessToken;
_30
const SyncGrant = AccessToken.SyncGrant;
_30
_30
// Used when generating any kind of tokens
_30
// To set up environmental variables, see http://twil.io/secure
_30
const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;
_30
const twilioApiKey = process.env.TWILIO_API_KEY;
_30
const twilioApiSecret = process.env.TWILIO_API_SECRET;
_30
const twilioSyncService = process.env.TWILIO_SYNC_SERVICE_SID;
_30
_30
// Used specifically for creating Sync tokens
_30
const identity = 'user';
_30
_30
// Create a "grant" which enables a client to use Sync as a given user
_30
const syncGrant = new SyncGrant({
_30
serviceSid: twilioSyncService,
_30
});
_30
_30
// Create an access token which we will sign and return to the client,
_30
// containing the grant we just created
_30
const token = new AccessToken(
_30
twilioAccountSid,
_30
twilioApiKey,
_30
twilioApiSecret,
_30
{ identity: identity }
_30
);
_30
token.addGrant(syncGrant);
_30
_30
// Serialize the token to a JWT string
_30
console.log(token.toJwt());

Now you're ready to use your token. For client-side SDKs like Conversations, Voice, and Video, you will need to get the stringified token to your client-side code via Ajax or some other means.

Refer to the Identity and Access Tokens guides in the product documentation for Video, Conversations, Sync for more details.


Managing the lifecycle of Access Tokens

managing-lifecycle page anchor

You can use API keys to manage the lifecycle of Access Tokens.

Since each Access Token was created using an API Key, you can delete the API key to revoke all of the Access Tokens related to that API Key.


Rate this page: