The Twilio Voice Javascript SDK works in a flow in which our Client browser will connect to a URL. This URL will be your Backend server that hosts the application code and other endpoints that will make the application work successfully. One of the key points is the authentication of the client to the server. This part is done using Access Tokens.
Understanding Access Tokens and how the Twilio Voice SDK uses them
AccessTokens serve as credentials for the end clients and are the key piece that connects SDK-powered applications, Twilio, and server-side apps all together.
They are short-lived tokens 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.
A basic workflow between a Client SDK and the Backend Server will be something like this:
- Your server-side application has an endpoint at http://www.example.com/token.
- Your client-side application sends a GET request to your http://www.example.com/token endpoint to retrieve an AccessToken.
- Your server-side application receives the GET request. Using a Helper Library, your application creates an AccessToken and sends it in the response to the GET request from your client-side application.
- Your client-side application receives the AccessToken and registers the SDK application with Twilio.
The AccessToken’s grants.voice.outgoing.application_sid property contains the SID for a TwiML App. A TwiML App is a Twilio Resource which holds Voice and Messaging configuration URLs much like a phone number. For a Voice SDK application, you will only need the Voice Configuration URLs.
Why would you need to extract an access token?
Since they are a crucial key in the communication, as they contain important information to initiate and have the calls made, it is important that we are able to pull it for cases in which we want to troubleshoot particular scenarios.
If you're working with Twilio Support to troubleshoot a Voice SDK issue, very often they will request an access token from your application, so it can be validated. This article shows you how you can collect and provide that access token to aid in troubleshooting.
How to Extract an Access Token from a Client Web Browser
If you've not built logging functionality into your application to print the access token, you will need to retrieve from the browser. Below you can see how to do this for the most common browsers.
Google Chrome
Let us say, I am connecting to my Client SDK using URL:
In a Chrome Browser from Windows I can press Control + Shfit + C to go to the Inspect or Developer tools, in a Mac Computer I will do Command + Shift + C:
Once there, We need to make sure that we are recording the activity, that can be checked in the same Dev tools as it is highlighted in the image below:
After that, we can try testing making a live call, with the Network Tab open, that will display a long number of events, We can click in an "EndpointEvents" and in the Box next to the Event names we will have the possibility to visualize the Event Headers, Payload, Preview, Response, etc, We click on "Headers" as shown below:
From there we can see the Headers that are part of that POST request, and we can see the X-Twilio-Token Header that our Backend Server delivered to us.
Safari
We need to firstly enable to show the "Develop Menu", we can go with keyboard shortcut "Command - Comma" to open the Safari Settings, then we go to "Advanced" and from there we will check the box "show develop menu in menu bar"
Once activated we should be able to see the Develop Menu bar when we are in Safari, we go there and then click in "Connect Web Inspector"
In the bottom we will see the same inspection tools we had from Chrome, we then attempt another call and go to Network Tab, then we select "EndpointEvents" and go to "Headers" from there we will see the "X-Twilio-Token" header, as shown below:
Mozilla Firefox
From Firefox, we can do right click in the Web application client and we will click in "Inspect".
We will see the Inspect tools at the bottom of the browser and from there we do the same as before, click on Network, go to an "EndpointEvent" and then select the "Headers" that will show the "X-Twilio-Token".
Access Token structure and how to decode it
Once you've collected your access token, you can decode it at https://jwt.io/. Simply paste the full access token without any headers or spaces into the field on the left then click decode.
This is an example of a decoded Voice Access Token:
"jti": "SKxxxx...-1643993631",
"grants": {
"identity": "alice",
"voice": {
"incoming": {
"allow": true
},
"outgoing": {
"application_sid": "APxxxx..."
},
"push_credential_sid": "CRxxxx..."
}
},
"iat": 1643993631,
"exp": 1643997231,
"iss": "SKxxxx...",
"sub": "ACxxxx..."Common issues with access tokens and things to verify
Once decoded, you can verify important things like the Account SID, TwiML App SID, expiration date/time, API Key SID, Push Credential SID (for mobile SDKs), identity, and grants. If anything is malformed or mismatched, you will often see a generic connection error when trying to make or receive calls as your SDK client will be unable to register with Twilio since the access token is invalid. If you're having issues with a Voice SDK application and you're not sure why, validating your access token is the first step in troubleshooting as it can be the root cause of many symptoms. One thing to check is that the account SID, API key, TwiML App, and push credential (mobile SDKs only) are all valid and in the same account or subaccount.
Twilio Customer Support
For additional assistance troubleshooting Voice SDK issues or validating access tokens, please reach out to Twilio Customer Support with an explanation of the issue along with your access token to expedite resolution.