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.
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.
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.
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.
The unique string that we created to identify the Key resource.
^SK[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The date and time in GMT that the resource was created specified in RFC 2822 format.
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.
application/x-www-form-urlencoded
The SID of the Account that created the Payments resource.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
A descriptive string that you create to describe the resource. It can be up to 64 characters long.
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.
restricted
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createNewKey() {11const key = await client.iam.v1.keys.create({12accountSid: "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13});1415console.log(key.sid);16}1718createNewKey();
1{2"sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",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"secret": "foobar",7"policy": null8}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createNewKey() {11const key = await client.iam.v1.keys.create({12accountSid: "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13});1415console.log(key.sid);16}1718createNewKey();
1{2"sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",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"secret": "foobar",7"policy": {8"allow": [9"/twilio/messaging/messages/read"10]11}12}
GET https://iam.twilio.com/v1/Keys/{Sid}
Returns a representation of the API Key, including the properties below.
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.
The Twilio-provided string that uniquely identifies the Key resource to fetch.
^SK[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchKey() {11const apiKey = await client.iam.v112.apiKey("SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.fetch();1415console.log(apiKey.sid);16}1718fetchKey();
1{2"sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",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": null7}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchKey() {11const apiKey = await client.iam.v112.apiKey("SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.fetch();1415console.log(apiKey.sid);16}1718fetchKey();
1{2"sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",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}
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.
The SID of the Account that created the Payments resource.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
How many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Maximum: 1000
The page token. This is provided by the API.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listGetKeys() {11const getApiKeys = await client.iam.v1.getApiKeys.list({12accountSid: "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13limit: 20,14});1516getApiKeys.forEach((g) => console.log(g.sid));17}1819listGetKeys();
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}
POST https://iam.twilio.com/v1/Keys/{Sid}
The Twilio-provided string that uniquely identifies the Key resource to update.
^SK[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
application/x-www-form-urlencoded
A descriptive string that you create to describe the resource. It can be up to 64 characters long.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateKey() {11const apiKey = await client.iam.v112.apiKey("SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.update({ friendlyName: "FriendlyName" });1415console.log(apiKey.sid);16}1718updateKey();
1{2"sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"friendly_name": "FriendlyName",4"date_created": "Mon, 13 Jun 2016 22:50:08 +0000",5"date_updated": "Mon, 13 Jun 2016 22:50:08 +0000",6"policy": null7}
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateKey() {11const apiKey = await client.iam.v112.apiKey("SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.update({ friendlyName: "FriendlyName" });1415console.log(apiKey.sid);16}1718updateKey();
1{2"sid": "SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"friendly_name": "FriendlyName",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 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.
The Twilio-provided string that uniquely identifies the Key resource to delete.
^SK[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteKey() {11await client.iam.v1.apiKey("SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();12}1314deleteKey();