Menu

Expand
Rate this page:

Twilio API: Access Tokens

Access Tokens are short-lived tokens that you can use to authenticate Twilio Client SDKs like Voice , Conversations, Sync 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.

Contents

How to create Access 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 you can create an Access Token in our application.

Step 1: Create an API Key

First, you need to create an API key. This contains a secret which will be used to sign Access Tokens. You can create API keys from the Twilio Console or using the REST API. When you create the API key, you’ll be shown the key’s secret. For security, you will only be shown the secret at this time, so you should store it with the key’s SID in a secure location for the next step.

Step 2: Generate an Access Token

Now use your new API key’s secret to generate an Access Token using a Twilio Helper Library. Each token is granted access to specific client features. Below is an example which demonstrates how to generate tokens that grant access to Conversations, Voice, Video and Sync.

When creating an Access Token, you must provide your Twilio Account SID, API key, and API secret. You can also optionally provide any of the following JWT configuration values.

Parameter Description Example
identity The identity of the first person. Typically a username in your system. Voice tokens may only contain alpha-numeric and underscore characters. user_name
ttl Time to live for the token, in seconds 3600
nbf Token not before time, or the time before which the token will NOT be accepted. Measured as seconds since epoch 1615404972
region The intended Twilio region for the token us1

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.

We recommend following the standard URI specification and avoid the following reserved characters ! * ' ( ) ; : @ & = + $ , / ? % # [ ] for values such as identity and friendly name.

        
        
        
              
              
              
                    
                    
                    
                          
                          
                          
                                
                                
                                

                                Step 3: Authenticate

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

                                Managing the lifecycle of Access Tokens

                                Your application will use API keys to manage the lifecycle of Access Tokens as follows:

                                The JSON Web Token format

                                Each Access Token is a JSON Web Token (JWT), an encoded JSON object with three parts: the header, the payload, and the signature. The following is a JWT token generated for Conversations 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:

                                • 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".

                                Payload

                                {
                                  "jti": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-1450471147",
                                  "iss": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                                  "sub": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                                  "iat": 1450471147,
                                  "nbf": 1450471147,
                                  "exp": 1450474747,
                                  "grants": {
                                    "identity": "user_name",
                                    "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 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. Client SDK (Conversations, 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 key secret, which should only be known to your application and Twilio.

                                Rate this page:

                                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 Community Forums or browsing the Twilio tag on Stack Overflow.

                                      
                                      
                                      

                                      Thank you for your feedback!

                                      We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      Refer us and get $10 in 3 simple steps!

                                      Step 1

                                      Get link

                                      Get a free personal referral link here

                                      Step 2

                                      Give $10

                                      Your user signs up and upgrade using link

                                      Step 3

                                      Get $10

                                      1,250 free SMSes
                                      OR 1,000 free voice mins
                                      OR 12,000 chats
                                      OR more