LOG IN SIGN UP
Documentation

To use the Fastly API you will need to create a valid API token. This token will be used to authenticate your API requests.

API tokens

API tokens are unique authentication identifiers that you can create for the users and applications authorized to interact with your service. You can restrict the access of tokens to a single service, and you can limit the capabilities of tokens using a scope other than the default global scope. For example the purge_select scope will limit a token to only be able to purge by URL and surrogate keys. Because users can create multiple API tokens, you can rotate tokens without taking services offline, and you can revoke individual tokens without having to update other API integrations.

Managing tokens with the web interface

You can use the Fastly web interface to create, view, and delete API tokens associated with your personal account. Superusers can view and delete any of the API tokens associated with the organization's Fastly account. See Using API tokens for more information.

Two-factor authentication

API tokens support two-factor authentication. Send the generated one-time password via the Fastly-OTP header when creating a token, as shown below.

POST https://api.fastly.com/tokens
Fastly-OTP: 123456
username=youremail@example.com&password=PASSWORD

Availability

All endpoints that support the legacy API keys also support API tokens. In addition to checking if the user is authenticated, the API will check if the user's role is authorized to perform the requested action. For example, billing endpoints will require an API token issued by a billing user (or superuser).

Access

You can limit a token's capabilities using scopes, and you can limit a token's authorizations by defining only those services you want it to access.

Scopes

Scopes can be used to limit a token's capabilities. The following scopes are currently supported:

To create a token with a single scope, specify the scope name in the body of the POST request. To create a token with multiple scopes, separate the names with a space (e.g., scope=purge_all purge_select global:read).

Services

Tokens are granted access to all services in an account by default. However, you can limit a token's access to one or more services. Do this by specifying an array in the POST /tokens action (e.g., services[]=id1&services[]=id2).

Expiration

You can optionally set API tokens to expire at a specified date and time. After a token expires, using it for any request will return an HTTP 401 response. Specify the expiration date by using the expires_at parameter in the POST /tokens action. Format the date and time in ISO 8601 format (e.g., 2016-07-28T19:24:50+00:00).

Using API tokens

To authenticate API requests, a valid Fastly API token should be included in the Fastly-Key HTTP header.

Deleting a user with active tokens

You can't delete a user who has active API tokens associated with their account. You must revoke the user's API tokens before deleting the user.

Limitations

API tokens currently have the following limitations:

API reference

Tokens

An API Token is used to identify who the API call is made on behalf of. It can also be used to restrict what an app can do through authorization scope. Users can create multiple tokens to suit their needs.

Fields

field type description
id string

The alphanumeric string identifying a token.

user_id string

The alphanumeric string identifying a user.

services array

List of alphanumeric strings identifying services (optional). If no services are specified, the token will have access to all services on the account.

access_token string

The alphanumeric string for accessing the API (only available on token creation).

name string

Name of the token.

scope string

Space-delimited list of authorization scope (optional, defaults to "global").

created_at string

Time-stamp (UTC) of when the token was created.

last_seen_at string

Time-stamp (UTC) of when the token was last used.

expires_at string

Time-stamp (UTC) of when the token will expire (optional).

ip string

IP Address of the client that last used the token.

user_agent string

User-Agent header of the client that last used the token.

Actions

GET /tokens

List all tokens belonging to the authenticated user.

Authentication

API token with at least Billing permissions.

Request Example
GET /tokens HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "5Yo3XXnrQpjc20u0ybrf2g",
    "user_id": "4y5K5trZocEAQYkesWlk7M",
    "services": [],
    "name": "my_token",
    "scope": "global",
    "created_at": "2016-06-22T03:19:48+00:00",
    "last_seen_at": "2016-06-22T03:19:48+00:00",
    "expires_at": "2016-07-28T19:24:50+00:00",
    "ip": "127.17.202.173",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36"
  }
]
GET /customer/id/tokens

List all tokens belonging to a specific customer

Authentication

API token with at least Billing permissions.

Request Example
GET /customer/:id/tokens HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "5Yo3XXnrQpjc20u0ybrf2g",
    "user_id": "4y5K5trZocEAQYkesWlk7M",
    "services": [],
    "name": "my_token",
    "scope": "global",
    "created_at": "2016-06-22T03:19:48+00:00",
    "last_seen_at": "2016-06-22T03:19:48+00:00",
    "expires_at": "2016-07-28T19:24:50+00:00",
    "ip": "127.17.202.173",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36"
  }
]
GET /tokens/self

Get a single token based on the access_token used in the request.

Authentication

API token.

Request Example
GET /tokens/self HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "5Yo3XXnrQpjc20u0ybrf2g",
  "user_id": "4y5K5trZocEAQYkesWlk7M",
  "services": [],
  "name": "my_token",
  "scope": "global",
  "created_at": "2016-06-22T03:19:48+00:00",
  "last_seen_at": "2016-06-22T03:19:48+00:00",
  "expires_at": "2016-07-28T19:24:50+00:00",
  "ip": "127.17.202.173",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36"
}
POST /tokens

Create an API token. If two-factor authentication is enabled for your account, review the instructions for including a one-time password in the request.

Authentication

Username and password.

Request Example
POST /tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
"username=me@example.com&password=secret&services[]=5VqE6MOOy1QFJbgmCK41pY&services[]=6VqE6MOOy1QFJbgmCK41pZ&expires_at=2016-07-28T19:24:50Z"
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "5Yo3XXnrQpjc20u0ybrf2g",
  "access_token": "YOUR_FASTLY_TOKEN",
  "user_id": "4y5K5trZocEAQYkesWlk7M",
  "services": ["5VqE6MOOy1QFJbgmCK41pY", "6VqE6MOOy1QFJbgmCK41pZ"],
  "name": "my_token",
  "scope": "global",
  "created_at": "2016-06-22T03:19:48+00:00",
  "last_seen_at": "2016-06-22T03:19:48+00:00",
  "expires_at": "2016-07-28T19:24:50+00:00",
  "ip": "127.17.202.173",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36"
}
DELETE /tokens/self

Revoke a token that is used to authenticate the request.

Authentication

API token.

Request Example
DELETE /tokens/self HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 204 No Content
Content-Type: application/json
DELETE /tokens/id

Revoke a specific token by its id.

Authentication

API token with at least Billing permissions.

Request Example
DELETE /tokens/5Yo3XXnrQpjc20u0ybrf2g HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 204 No Content
Content-Type: application/json
DELETE /tokens

Revoke Tokens in bulk format. Users may only revoke their own tokens. Superusers may revoke tokens of others.

Authentication

API token.

Request Example
DELETE /tokens HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/vnd.api+json; ext=bulk
Content-Type: application/vnd.api+json; ext=bulk
{
  "data" => [
    {
      "id" => "3krg2uUGZzb2W9Euo4moOY",
      "type" => "token",
    },
    {
      "id" => "71ZA6hv2FO6tGEQIE203Xj",
      "type" => "token",
    }
  ]
}
Response Example
HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json; ext=bulk

Troubleshooting

If the Fastly API returns an error message while you're working with API tokens, use the following information to troubleshoot the issue.

POST /tokens

A response with a JSON body containing an error code is returned on error.

HTTP response code Code Description
400 invalid_grant The supplied username/password combination is not correct.
400 invalid_request The username/password combination is not supplied. If you're using cURL on the command line, make sure the options are correct.
400 invalid_scope The supplied scope is not valid.
400 account_locked Your account is locked.
400 2fa.verify Your 2FA token is not supplied or is expired.
422 Unprocessable Entity The format of the date and time supplied to the expires_at parameter is invalid.

GET /tokens

GET /tokens/self

DELETE /tokens/:token_id

DELETE /tokens/self

Legacy API keys

If you created a Fastly account before May 15th, 2017, you may have used an API key (or multiple API keys) to authenticate API requests. This account-level credential was migrated to a personal API token with a global scope and access to all of your services. Because all tokens need to be owned by a user, this credential was assigned to a newly created, synthetic user with the name Global API Token.