On this page

REST API: Key Resource v1

This new REST API for the v1 Key resource allows you to create and manage API Keys, including Restricted API Keys which were not supported by the v2010 Key resource.

API Keys can be used to authenticate to Twilio APIs. 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.

(information)

Info

See this document for more information about making HTTP requests to Twilio's REST API.

API Keys can be provisioned and revoked through this resource or the Twilio Console. Keys provide a powerful and flexible way for managing access to the Twilio API. There are three types of API Keys: Standard, Main, and Restricted. The REST API only allows for creation and management of Standard and Restricted type API Keys. Main type API Keys can only be created using the Twilio Console.

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 delete it to prevent unauthorized access.

(warning)

Warning

If your use case requires API Keys to access the /Accounts or /Accounts/sid<AC>/Keys endpoint, a Main Key needs to be used. Main Keys can only be created in the Console and cannot be created via API.

Types of Keys

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.

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.

Key Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<SK>

Optional

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

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

friendly_namestring

Optional

The string that you assigned to describe the resource.

date_createdstring<date-time-rfc-2822>

Optional

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

date_updatedstring<date-time-rfc-2822>

Optional

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

Create an API Key

POST https://iam.twilio.com/v1/Keys

To create Standard or Restricted 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, which is how you create API Keys via API.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

AccountSidSID<AC>required

The SID of the Account that created the Payments resource.

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

FriendlyNamestring

Optional

PII MTL: 30 days

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

KeyTypeenum<string>

Optional

The `KeyType` form parameter is used to specify the type of key you want to create.

Default Behavior: If `KeyType` is not specified, the API will generate a standard key.

Restricted Key: If `KeyType` is set to `restricted`, the API will create a new restricted key. In this case, a policy object is required to define the permissions.

Possible values:

restricted

Policyobject

Optional

The `Policy` object is a collection that specifies the allowed Twilio permissions for the restricted key. For more information on the permissions available with restricted API keys, refer to the Twilio documentation.

Create a Standard API Key

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createNewKey() {
11  const newApiKey = await client.iam.v1.newApiKey.create({
12    accountSid: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13    friendlyName: "Mario's API Key",
14  });
15
16  console.log(newApiKey.sid);
17}
18
19createNewKey();

Output

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  "policy": null
8}

Create a Restricted API Key

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createNewKey() {
11  const newApiKey = await client.iam.v1.newApiKey.create({
12    accountSid: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13    friendlyName: "Mario's API Key",
14    keyType: "restricted",
15    policy: {
16      allow: ["/twilio/messaging/messages/read"],
17    },
18  });
19
20  console.log(newApiKey.sid);
21}
22
23createNewKey();

Output

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  "policy": {
8    "allow": [
9      "/twilio/messaging/messages/read"
10    ]
11  }
12}

Fetch a Key resource

GET https://iam.twilio.com/v1/Keys/{Sid}

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.

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<SK>required

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 a Standard API Key

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchKey() {
11  const apiKey = await client.iam.v1
12    .apiKey("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1")
13    .fetch();
14
15  console.log(apiKey.sid);
16}
17
18fetchKey();

Output

1{
2  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1",
3  "friendly_name": "foo",
4  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
5  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",
6  "policy": null
7}

Fetch a Restricted API Key

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchKey() {
11  const apiKey = await client.iam.v1
12    .apiKey("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2")
13    .fetch();
14
15  console.log(apiKey.sid);
16}
17
18fetchKey();

Output

1{
2  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2",
3  "friendly_name": "foo",
4  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
5  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",
6  "policy": {
7    "allow": [
8      "/twilio/messaging/messages/read"
9    ]
10  }
11}

List Key resources

GET https://iam.twilio.com/v1/Keys

Returns a list of API Keys associated with a given Account, sorted by DateUpdated.

The list includes all API Keys and paging information.

Query parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account that created the Payments resource.

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

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

List Key resources

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listGetKeys() {
11  const getApiKeys = await client.iam.v1.getApiKeys.list({
12    accountSid: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13    limit: 20,
14  });
15
16  getApiKeys.forEach((g) => console.log(g.sid));
17}
18
19listGetKeys();

Output

1{
2  "keys": [
3    {
4      "sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "friendly_name": "foo",
6      "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
7      "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000"
8    },
9    {
10      "sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
11      "friendly_name": "bar",
12      "date_created": "Mon, 13 Jun 2016 20:50:08 +0000",
13      "date_updated": "Mon, 13 Jun 2016 20:50:08 +0000"
14    }
15  ],
16  "meta": {
17    "page": 0,
18    "page_size": 50,
19    "first_page_url": "https://iam.twilio.com/v1/Keys?AccountSid=ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
20    "previous_page_url": null,
21    "url": "https://iam.twilio.com/v1/Keys?AccountSid=ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
22    "next_page_url": null,
23    "key": "keys"
24  }
25}

Update a Key resource

POST https://iam.twilio.com/v1/Keys/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<SK>required

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

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

FriendlyNamestring

Optional

PII MTL: 30 days

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

Policyobject

Optional

The `Policy` object is a collection that specifies the allowed Twilio permissions for the restricted key. For more information on the permissions available with restricted API keys, refer to the Twilio documentation.

Attempts to update the fields of an API Key resource.

If successful, it returns the updated resource representation. The response will be identical to that of the Fetch a Key resource endpoint.

Update a Standard Key resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateKey() {
11  const apiKey = await client.iam.v1
12    .apiKey("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .update({ friendlyName: "friendly_name" });
14
15  console.log(apiKey.sid);
16}
17
18updateKey();

Output

1{
2  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "friendly_name": "friendly_name",
4  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
5  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",
6  "policy": null
7}

(information)

Update a Restricted Key

The update action requires all permissions to be included in the policy object, as it will completely overwrite the existing policy associated with the original Key. To remove a specific permission while retaining others, it is necessary to reapply all the permissions that should be kept.

Update a Restricted Key resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateKey() {
11  const apiKey = await client.iam.v1
12    .apiKey("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .update({
14      friendlyName: "friendly_name",
15      policy: {
16        allow: [
17          "/twilio/messaging/messages/read",
18          "/twilio/messaging/messages/update",
19        ],
20      },
21    });
22
23  console.log(apiKey.sid);
24}
25
26updateKey();

Output

1{
2  "sid": "SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "friendly_name": "friendly_name",
4  "date_created": "Mon, 13 Jun 2016 22:50:08 +0000",
5  "date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",
6  "policy": {
7    "allow": [
8      "/twilio/messaging/messages/read",
9      "/twilio/messaging/messages/update"
10    ]
11  }
12}

Delete a Key resource

DELETE https://iam.twilio.com/v1/Keys/{Sid}

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 deletion is successful, Twilio will return an HTTP 204 response with no body.

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<SK>required

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteKey() {
11  await client.iam.v1.apiKey("SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").remove();
12}
13
14deleteKey();