On this page

Migrate Capability Tokens to Access Tokens

(information)

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).

Introduction

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.

Reasons to migrate

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.

Migration steps

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.

Step 1: Generate an API Key for your application

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.

Step 2: Update your application code

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.

(information)

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.

Step 3: Deploy and test your application

Deploy your updated application and verify correct behavior.

Parameter Mapping Table

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.

(information)

Info

With Access Tokens, the identity parameter is always required and will be used as the client name for both incoming and outgoing calls.