Twilio API: Access Tokens

Access Tokens are short-lived tokens that you can use to authenticate Twilio Client SDKs like Voice, Chat and Video. You create them on your server to verify a client's identity and grant access to client API features. All tokens have a limited lifetime, configurable up to 24 hours. However, a best practice is to generate Access Tokens for the shortest amount of time feasible for your application.

Table of Contents

• Creating Tokens
• JWT Format

Creating Tokens

Twilio Access Tokens are based on the JSON Web Token standard. You can read about the details of the JWT format for Access Tokens here, but if you're using one of Twilio's official helper libraries you can use our token-generation functionality without having to know how they're constructed.

Let's see how we can create an access token in our application.

Step 1: Create an API Key

First, you need to create an API Key, which contains a secret used to sign Access Tokens. You can create API Keys from the Twilio Console or using the REST API. At the time you create the API Key, you'll be shown the Key's secret. For security, you will only be shown the secret when the key is created. You should store it with the Key's SID in a secure location for the next step.

Step 2: Generate an Access Token

Next, you'll use the the secret of the API Key you created in step 1 to generate an access-token using the Twilio Helper Library. Each token is granted access to specific client features. Here is an example of how to generate tokens that grant access to Chat:

Step 3: Authenticate

Now you're ready to use your token. For client-side SDKs like Chat 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 or Chat for more details.

Managing the Lifecycle of Access Tokens using API Keys

Your application will use API Keys to manage the lifecycle of Access Tokens using a few basic steps:

• Create an API Key using the REST API and store the secret returned. You can also manage API keys in the console for your product.
• Use the Twilio Helper Libraries and the API Key's Secret to generate Access Tokens for clients.
• Delete the API Key to revoke all of the Access Tokens generated using it.

JWT Format

Each Access Token is a JWT, which is an encoded JSON object with three parts: the header, the payload, and the signature. The following is a JWT token generated for Chat using code similar to the example above:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImN0eSI6InR3aWxpby1mcGE7dj0xIn0.eyJqdGkiOiJTS3h4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4LTE0NTA0NzExNDciLCJpc3MiOiJTS3h4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4Iiwic3ViIjoiQUN4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eCIsIm5iZiI6MTQ1MDQ3MTE0NywiZXhwIjoxNDUwNDc0NzQ3LCJncmFudHMiOnsiaWRlbnRpdHkiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaXBfbWVzc2FnaW5nIjp7InNlcnZpY2Vfc2lkIjoiSVN4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eCIsImVuZHBvaW50X2lkIjoiSGlwRmxvd1NsYWNrRG9ja1JDOnVzZXJAZXhhbXBsZS5jb206c29tZWlvc2RldmljZSJ9fX0.IHx8KeH1acIfwnd8EIin3QBGPbfnF-yVnSFp5NpQJi0

If we inspect it with the debugger at jwt.io, we can further explore its content.

Header

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

The header section encodes the format of the token:

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

Payload

{
  "jti": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-1450471147",
  "iss": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "sub": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "nbf": 1450471147,
  "exp": 1450474747,
  "grants": {
    "identity": "user@example.com",
    "chat": {
      "service_sid": "ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

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 whose secret signs the token.
• sub is the Sid of the account to which access is scoped.
• nbf is the timestamp on which the token was generated.
• exp is the timestamp on which the token will expire. Tokens have a maximum age of 24 hours.
• grants is the list of granted permissions the token has. Client SDK (Chat, Video) grant values will vary from SDK to SDK.

Signature

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 secret, which should only be known to your application and Twilio.