Skip to contentSkip to navigationSkip to topbar
On this page

Restricted API Keys


(information)

Public Beta Notice

Restricted API Keys are currently available as a public beta release. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA.

Learn more about beta product support(link takes you to an external page).

Restricted API Keys allow you to decide which Twilio API Resources an API Key can access, and which action(s) the API Key is allowed to take on those API Resources. You can now create and manage Restricted API Keys using REST APIs, in addition to using Twilio Console.

Restricted API Keys currently allow you to grant API access to specific Studio, Voice, Voice Intelligence, Voice Insights, Messaging, Long Codes, Regulatory Compliance, SIP, TaskRouter, Monitor Events, Monitor Alerts and Lookup endpoints. Please note, Twilio is actively adding more permissions to this product.

For example, if your Programmable Voice application's testing suite makes test Voice calls, you can create a Restricted API Key that is only permitted to send POST requests to create Call Resources.

Or you can create Restricted API Keys that provide your engineering team with access to every Voice endpoint except the Call Recording Resource endpoints.

(warning)

Warning

Currently, you cannot create Access Tokens for Twilio's client-side SDKs if you're using Restricted API Keys.


Create a Restricted API Key

create-a-restricted-api-key page anchor

You can create and manage Restricted API Keys using REST APIs. If you'd like to use the Twilio Console, please complete the following steps to create a Restricted API Key.

  1. Log into your Twilio Console(link takes you to an external page).

  2. Click on Account in the upper right corner.

  3. In the dropdown menu, under Keys & Credentials , select API Keys & tokens. (Note: You may need to authenticate your Twilio Account at this point.)

    Screenshot of Twilio Console highlighting 'Accent' menu in top right corner and 'API Keys and tokens' link.
  4. On the API Keys page, click on the Create API Key button.

  5. On the Create new API key page, input a Friendly name.

  6. If your account has Twilio Regions enabled, ensure that the Region selected is United States - Default.

  7. For the Key Type field, select Restricted.

  8. A Permissions section appears with a grid showing Twilio API Resources and endpoints (i.e., Read, List, Create, Update, and Delete). Select the permissions you want for this API Key.

    Screenshot of Create new API Key page in Console with Friendly name filled out, Region set to United States - Default, Key Type set to Restricted, and some Permissions selected.
  9. Click the Create button at the bottom of the page.

  10. On the Copy secret key page, Copy the Secret and store it somewhere secure.

  11. Click on the Got it! checkbox and click Done.


Authenticate with a Restricted API Key

authenticate-with-a-restricted-api-key page anchor

The SID of the Restricted API Key and the associated secret (from step 10 above) are used as your credentials when sending API requests to Twilio.

Read the Requests to Twilio page to learn more.


Modify a Restricted API Key

modify-a-restricted-api-key page anchor

To modify the friendly name or the permissions of a Restricted API Key, follow the directions below.

  1. Log into your Twilio Console(link takes you to an external page).
  2. Click on Account in the upper right corner.
  3. In the dropdown menu, under Keys & Credentials , select API Keys. (Note: You may need to authenticate your Twilio Account at this point.)
  4. On the API Keys page, select the API Key you wish to modify by clicking on the Key's name or SID.
  5. Modify the Friendly name and/or Permissions for the Key.
  6. Click Save.

Duplicate a Restricted API Key

duplicate-a-restricted-api-key page anchor

Duplicating a Restricted API Key is a convenience feature that allows you to create a new Restricted API Key with the same permissions as another Restricted API Key. You can then modify the Friendly name and permissions with the new Key.

You can duplicate a Restricted API Key in two ways:

  • From the API keys & tokens page in the Console

    • In the Console, navigate to Account > API Keys & tokens. Select the Duplicate key action next to the Key you want to duplicate. \

      Highlighting the 'Duplicate key' option on the API keys & tokens page in the Console.
  • Via the Restricted API Key's info page

    • In the Console, navigate to Account > API Keys & tokens and select the Restricted API Key you wish to duplicate. On the Key's details page, click on the Duplicate this key button at the bottom of the page.

      Delete this API Key option in Console.

Delete a Restricted API Key

delete-a-restricted-api-key page anchor
  1. In the Twilio Console, click on Account in the upper right corner.

  2. In the dropdown menu, under Keys & Credentials , select API Keys. (Note: You may need to authenticate your Twilio Account at this point.)

  3. On the API Keys page, select the API Key you wish to delete by clicking on the Key's name or SID.

  4. Click Delete this API key at the bottom of the page.

    Delete this API Key option in Console.
  5. In the pop-up, confirm your choice by clicking Delete this API key.


Permissions available with Restricted API Keys

permissions-available-with-restricted-api-keys page anchor

Restricted API Keys allow you to select specific API endpoints that the Key is authorized to access. Currently, you can grant these permissions for Studio, Voice, Messages, Long Codes, and SIP endpoints.

Each permission maps to one or more endpoints/actions for each API Resource.

Click on one of the product areas below to download a PDF of the permissions/endpoint actions.

Twilio Restricted API Keys Permissions - Messaging Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - Phone Numbers Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - Studio Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - TaskRouter Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - Voice Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - Lookup Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - API Keys Permissions(link takes you to an external page)

Twilio Restricted API Keys Permissions - Monitor Permissions(link takes you to an external page)

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.