API Key

How do API Keys differ from Account credentials?

When you create a Twilio Account, Twilio generates an Account SID (String IDentifier) and an Auth Token. These are your Account API credentials. Any time you share these credentials, say with a colleague, you increase the risk of those credentials becoming compromised. Luckily, Twilio also allows you to authenticate using API Keys.

API Keys are the preferred way to authenticate to Twilio’s services. There are two types of API Key: Standard and Main.

Standard API Keys give you access to all the functionality in Twilio’s API except for managing API Keys themselves, and configuring Accounts and Subaccounts.

Main API Keys have the same access as standard keys, but can also be used to manage API Keys, and configure Accounts and Subaccounts. Main keys give you the same level of access you get when you use your Account credentials.

How can I create API Keys?

You can create API Keys from the Twilio Console by following these steps:

1. Navigate to Settings and select API Keys, or simply follow this link.
2. Click the Create new API Key button, or click on the plus (+) icon if you have other API Keys already.
3. Enter a friendly name for your API Key.
4. Select the key type — Standard or Main.
5. Click the Create API Key button.

Once the API Key has been created, you’ll be presented with the key and a secret. This secret serves as the key’s password, much as your account’s Auth Token serves as the password for your Account SID. Please take note of the secret and ensure that you save it securely, as it is only shown once and can’t be viewed later.

You can also create standard API Keys using the Twilio CLI, SDK, and API as shown in the Twilio documentation.

How do I authenticate with an API Key?

Instead of authenticating with Twilio using your Account SID and Auth Token, you can now use your new API Key, its secret, and your Account SID.

For example, if you were creating a Twilio Client in Node.js with the account credentials — and assuming you have your credentials set as environment variables — you would use this code:

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

Creating a Twilio Client using an API key is very similar. Again, you’ll need to include your Account SID:

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = require('twilio')(apiKey, apiSecret, { accountSid });

When interacting with the API directly instead of using a helper library, you simply use the API Key and secret as your Basic Auth header, like so:

curl -X GET 'https://api.twilio.com/2010-04-01/Accounts.json?PageSize=20' \
  -u $TWILIO_API_KEY:$TWILIO_API_SECRET