API Keys Overview

You can use your Account SID and Auth Token as your API credentials for local testing, but using them in production is risky. If a bad actor gains access to your Account SID and Auth Token, your Twilio Account is compromised. This could cost you money and harm your business's reputation.

Instead, you can create API Keys for your applications and software developers. This gives you complete control of the lifecycle of your Twilio Accounts' API credentials. If an API Key is compromised or no longer used, you can delete the API Key to protect your Twilio Account from unauthorized access.

In addition, you can scope access for an API Key using Restricted API Keys. This allows you to reduce security risks by providing minimum and specific levels of access for your applications and API credentials.

There are three types of API Keys: Main, Standard and Restricted (Public Beta).

• Main API Keys provide the most permissions. They give you the same level of access as using your Account SID and Auth Token in API requests.

  • Main API Keys provide access to the Account Resource of the Account that created the API Key. If you need API access to the Account Resource of a Subaccount, you need to create a Main API Key within the Subaccount.

• Standard API Keys give you access to all of the functionality in Twilio's APIs, _except_the following API Resources:

  • API Key Resources
  • Account Resources

• Restricted API Keys (Public Beta) allow you to provide fine-grained access to specific Twilio API Resources.

  • Read the Restricted API Key doc to learn more.

Create API Keys in the Twilio Console by following the steps below.

1. Click on Account in the top right-hand corner.
2. Under Keys & credentials, click on API keys & tokens (or follow this link).
3. On the API keys & tokens page, click on the Create API Key button.
4. On the Create new API key page, enter a Friendly name for the API Key.
5. Select the key type: Restricted, Standard, or Main.
6. Click the Create API Key button.
7. On the Copy secret key page, Copy the Secret and store it somewhere secure.
8. Click on the Got it! checkbox and click Done.

Not sure how to use the API Key and Secret? Check out the Make an HTTP Request to Twilio page.

To create API Keys via API, you must use your Account SID and Auth Token or a Main API Key as your credentials. You can also use a Restricted API Key to create API keys as long as it has the permission for /twilio/iam/api-keys/create.

The code sample below shows a POST request to a Twilio Account's Key Resource, which is how you create API Keys via API.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createNewKey() {
11
  const newKey = await client.newKeys.create({
12
    friendlyName: "Mario's API Key",
13
  });
14

15
  console.log(newKey.sid);
16
}
17

18
createNewKey();

1
{
2
  "sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "friendly_name": "Mario's API Key",
4
  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
5
  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",
6
  "secret": "foobar"
7
}

Below is a sample response to this POST request. The response contains a sid property and a secret property. Store the secret in a secure location, because you won't be able to retrieve it again.

1
{
2
  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "friendly_name": "Mario's API Key",
4
  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
5
  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",
6
  "secret": "someLongAlphanumericString"
7
}

The Key Resource's sid and the secret are used as the credentials when making requests to Twilio's APIs.

If you ever no longer use an API Key or if a Key has been compromised, you can revoke the Key's permissions by deleting the API Key. You can do this in the Twilio Console or programmatically with Twilio's REST API.

Follow the directions below to delete an API Key from within the Twilio Console.

1. Click on Account in the top right-hand corner.
2. Under Keys & credentials, click on API keys & tokens (or follow this link).
3. On the API keys & tokens page, select the key you wish to delete.
4. On the API Key's details page, click Delete this API key located at the bottom of the screen.
5. In the pop-up, click Delete this API key to confirm your decision.

To delete API Keys via API, you must use your Account SID and Auth Token or a Main API Key as your credentials. You can also use a Restricted API Key to delete API keys as long as it has the permission for /twilio/iam/api-keys/delete.

The code sample below shows a DELETE request to a specific Key Resource's URI, which is how you delete API Keys via API.

You need the Key Resource's SID to complete this action. The Key's SID is returned in the response when you create the Key and can be found in the Twilio Console, or by reading your Account's Key Resources.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function deleteKey() {
11
  await client.keys("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").remove();
12
}
13

14
deleteKey();

If you plan on using a client-side SDK with Twilio, you need to create Access Tokens. Learn more on the Access Tokens page.

Learn how to safely store your API Keys in environment variables in the "How to Set Environment Variables" Blog post.

Read the "Guide to Basic API Security Best Practices" Blog post.

Find the docs you need so you can start building!