REST API: API Keys
API Keys represent credentials to access the Twilio API. They are used for two purposes:
- to authenticate to the REST API.
- to create and revoke Access Tokens
API Keys can be provisioned and revoked through the REST API or the Account Console, providing a powerful and flexible primitive for managing access to the Twilio API. For instance, you might issue separate API Keys to different developers, or to different subsystems within your application. Since API Keys can be independently revoked, you have complete control of the lifecycle of your API credentials.
Note: If your use case require API Keys to access the /Accounts or /Keys endpoint, a Master Key needs to be used, which can be created in the Console.
An example of using API keys to authenticate a REST API request is below.
API Key Instance Resource
Resource URI
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Keys/{API KeySid}
Resource Properties
An API Key is represented by the following properties:
date_created
|
The date-time this API Key was created, given as a RFC 2822 Timestamp. |
date_updated
|
The date-time this API Key was most recently updated, given as a RFC 2822 Timestamp. |
friendly_name
|
A descriptive string for this resource, chosen by your application, up to 64 characters long. |
sid
|
A 34 character string that uniquely identifies this API Key. You will use this as the basic-auth |
HTTP GET
Returns a representation of the Key, including the properties above.
Note that for security reasons, the Secret field is ONLY returned when the API Key is first created.
Example
An example API Key. Note that the API Key's Secret field is redacted; Secret fields are only returned when the API Key is first created.
HTTP POST
Attempts to update the fields of an API Key instance and returns the updated resource representation if successful. If successful, the response will be identical to that of the HTTP GET.
Optional Parameters
You may specify one or more of the following parameters to update this API Key's properties:
FriendlyName
Optional
|
A descriptive string for this resource, chosen by your application, up to 64 characters long. |
HTTP PUT
Not supported.
HTTP DELETE
Delete 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.
Note that you may only delete Keys by authenticating with the account's AccountSid and AuthToken or API Keys that have the master key flag set in the console.
API Keys List Resource
Resource URI
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Keys
HTTP GET
Returns a list of API Keys in this account, sorted by DateUpdated. This list includes paging information.
All API Keys are included.
Example
Retrieve all the API Keys in an account:
HTTP POST
Creates a new API Key.
Note that you may only delete Keys by authenticating with the account's AccountSid and AuthToken or API Keys that have the master key flag set in the console.
Optional Parameters
Your request may include the following parameters:
| Parameter | Description |
|---|---|
| FriendlyName | A descriptive string for this resource, chosen by your application, up to 64 characters long. |
If successful, Twilio will respond with a representation of the new
API Key. This representation will be exactly the same as that
returned by issuing a GET to the API Key's instance resource,
except that the Secret field will be included.
For security reasons, the API Key's Secret is only returned here, when the API Key is first created. 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.
Example
Create an API Key with the FriendlyName "User Jenny".
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.