On this page

REST API: Key Resource

You access the Twilio API using API keys that represent the required credentials. These keys:

Authenticate to the REST API
Create and revoke Access Tokens

(information)

Info

See this document for more information about your request to Twilio's REST API, or read our article on Access Tokens to learn more.

API Keys can be provisioned and revoked through the REST API or the Twilio Console. This provides a powerful and flexible primitive for managing access to the Twilio API. There are two types of API Keys: Standard and Main.

Standard API Keys give you access to all the functionality in Twilio's API, except for managing API Keys, Account Configuration, and Subaccounts.

Main API Keys have the same access as Standard Keys, and can also manage API Keys, Account Configuration, and Subaccounts. Main API Keys give you the same level of access as if you were using account API Credentials.

Since API Keys can be independently revoked, you have complete control of the lifecycle of your API credentials.

For example, you might issue separate API Keys to different developers or different subsystems within your application. If a key is compromised or no longer used, you can easily delete it to prevent unauthorized access!

(warning)

Warning

If your use case requires API Keys to access the /Accounts or /Keys endpoint, a Main Key needs to be used. This can be created in the Console.

Key Properties

Property nameTypePIIDescription

sidSID<SK>

Not PII

The unique string that that we created to identify the Key resource.

Pattern: ^SK[0-9a-fA-F]{32}$Min length: 34Max length: 34

friendly_namestring

PII MTL: 30 days

The string that you assigned to describe the resource.

date_createdstring<date-time-rfc-2822>

Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_updatedstring<date-time-rfc-2822>

Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

Fetch a Key resource

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Keys/{Sid}.json

Returns a representation of the API Key, including the properties below.

(warning)

Warning

For security reasons, the Secret field is ONLY returned when the API Key is first created - never when fetching the resource. Your application should store the API Key's Sid and Secret in a secure location to authenticate to the API and generate Access Tokens in the future.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

Not PII

The SID of the Account that created the Key resource to fetch.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<SK>required

Not PII

The Twilio-provided string that uniquely identifies the Key resource to fetch.

Pattern: ^SK[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch an API Key

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function fetchKey() {
_16  const key = await client.keys("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").fetch();
_16
_16  console.log(key.sid);
_16}
_16
_16fetchKey();

Output


_10{
_10  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10  "friendly_name": "foo",
_10  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
_10  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000"
_10}

Fetch an API Key

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function fetchKey() {
_16  const key = await client.keys("SK2a0747eba6abf96b7e3c3ff0b4530f6e").fetch();
_16
_16  console.log(key.sid);
_16}
_16
_16fetchKey();

Output


_10{
_10  "sid": "SK2a0747eba6abf96b7e3c3ff0b4530f6e",
_10  "friendly_name": "foo",
_10  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
_10  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000"
_10}

Read a Key resource

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Keys.json

Returns a list of API Keys in this account, sorted by DateUpdated.

The list includes all API Keys. It also includes paging information.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

Not PII

The SID of the Account that created the Key resources to read.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

Not PII

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

Read a Key resource

Retrieve all the API Keys in an account

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function listKey() {
_16  const keys = await client.keys.list({ limit: 20 });
_16
_16  keys.forEach((k) => console.log(k.sid));
_16}
_16
_16listKey();

Output


_18{
_18  "keys": [
_18    {
_18      "sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18      "friendly_name": "foo",
_18      "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
_18      "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000"
_18    }
_18  ],
_18  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json?PageSize=50&Page=0",
_18  "end": 0,
_18  "previous_page_uri": null,
_18  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json?PageSize=50&Page=0",
_18  "page_size": 50,
_18  "start": 0,
_18  "next_page_uri": null,
_18  "page": 0
_18}

Update a Key resource

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Keys/{Sid}.json

Attempts to update the fields of an API Key instance.

If successful, it returns the updated resource representation. The response will be identical to that of the HTTP GET (fetch).

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

Not PII

The SID of the Account that created the Key resources to update.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<SK>required

Not PII

The Twilio-provided string that uniquely identifies the Key resource to update.

Pattern: ^SK[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Property nameTypeRequiredPIIDescription

FriendlyNamestringOptional

PII MTL: 30 days

A descriptive string that you create to describe the resource. It can be up to 64 characters long.

Update a Key resource

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function updateKey() {
_18  const key = await client
_18    .keys("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_18    .update({ friendlyName: "friendly_name" });
_18
_18  console.log(key.sid);
_18}
_18
_18updateKey();

Output


_10{
_10  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10  "friendly_name": "friendly_name",
_10  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
_10  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000"
_10}

Delete a Key Resource

DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Keys/{Sid}.json

Deletes an API Key. This revokes its authorization to authenticate to the REST API and invalidates all Access Tokens generated using its secret.

If the delete is successful, Twilio will return an HTTP 204 response with no body.

(warning)

Warning

You may only delete Keys by authenticating with the account's AccountSid and AuthToken or API Keys that have the main key flag set in the console.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

Not PII

The SID of the Account that created the Key resources to delete.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<SK>required

Not PII

The Twilio-provided string that uniquely identifies the Key resource to delete.

Pattern: ^SK[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete a Key resource

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_14// Download the helper library from https://www.twilio.com/docs/node/install
_14const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_14
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = twilio(accountSid, authToken);
_14
_14async function deleteKey() {
_14  await client.keys("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").remove();
_14}
_14
_14deleteKey();