Migrate Capability Tokens to Access Tokens
Info
This migration guide applies to any application that currently uses Capability Tokens. The migration steps are independent of which version of the Voice JS SDK you use (1.x or 2.x).
Twilio Capability Tokens are deprecated and will eventually reach end of life. The recommended approach is to use Access Tokens. This guide will help you migrate your existing use cases from Capability Tokens to Access Tokens.
- Improved Security:
- Capability Tokens require access to the auth token of your account, which poses a greater security risk.
- Access Tokens utilize API keys, which can provide distinct keys to your individual applications and access can be revoked at any time.
- Standardization Across Twilio Products:
- Capability Tokens only work with the Voice JS SDK.
- Access Tokens offer a standardized method for authentication across multiple Twilio products using a single token.
- Regional Support:
- Capability Tokens only supports the United States (US1) Twilio region.
- Access Tokens support all Twilio regions.
For full details on how to create Access Tokens see the Access Tokens Documentation. The steps below summarize the process of migrating from Capability Tokens to Access Tokens.
Use the Twilio Console or API to generate API keys. The keys should be distinct for each of your Twilio applications. For details see API Key documentation.
Update your server-sided application logic to generate tokens using the Access Token constructor. Refer to the Access Tokens Documentation for details on how to create Access Tokens in your programming language of choice. The Parameter Mapping Table below has additional details on how to convert parameters from Capability Tokens to Access Tokens.
Info
You do not need to change any client-sided logic regarding passing the token to the Voice JavaScript SDK. The client Device object is constructed the exact same way regardless of which token type is used.
Deploy your updated application and verify correct behavior.
| Capability Token Parameter | Access Token Parameter | Description |
|---|---|---|
accountSid | accountSid | Your Twilio Account SID. |
authToken | Do Not Use | Use an API Key to mint your Access Tokens instead. |
apiKeySid | The SID of the API Key you created. | |
apiKeySecret | The secret of the API Key you created. | |
ttl | ttl | Time-to-live for the token. |
Incoming: clientName | identity & incomingAllow=true | The client name and flag to enable incoming calls. |
Outgoing: clientName | identity | The client name for outgoing calls. |
Outgoing: applicationSid | outgoingApplicationSid | The TwiML application SID for outgoing calls. |
Outgoing: params | outgoingApplicationParams | Any additional parameters to be sent with the outgoing call request. |
Info
With Access Tokens, the identity parameter is always required and will be used as the client name for both incoming and outgoing calls.