LOG IN SIGN UP
Documentation

You authenticate to the Fastly API in one of three ways: via API tokens, API key, or a session.

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 scope the authorization of tokens to a single service, and you can restrict access to purge all by limiting tokens to purging 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.

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

Currently, all endpoints that support 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 for a billing user (or superuser).

Scopes

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

You can also scope the authorization of tokens to a single service by specifying the service_id in a parameter in the POST /tokens action.

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).

Backward compatibility

API tokens are compatible with API keys, and can be included in any API calls in the Fastly-Key HTTP header. The Fastly API will check the provided key against both API keys as well as API tokens. Fastly API clients can use an API token value instead of an existing API key.

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.
service_id string The alphanumeric string identifying a service (optional).
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 "api-key").
created_at string Time-stamp (UTC) of when the token was created.
expires_at string Time-stamp (UTC) of when the token will expire (optional).

Actions

GET /tokens

List all tokens belonging to the authenticated user.

Authentication

API token

Request Example
GET /tokens
Fastly-Key: d3cafb4dde4dbeef
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "5Yo3XXnrQpjc20u0ybrf2g",
"user_id": "4y5K5trZocEAQYkesWlk7M",
"service_id": null,
"name": "my_token",
"scope": "api-key",
"created_at": "2016-06-22T03:19:48+00:00"
"expires_at": "2016-07-28T19:24:50+00:00",
}
]

GET /customer/id/tokens

List all tokens belonging to a specific customer

Authentication

API token

Request Example
GET /customer/:id/tokens
Fastly-Key: d3cafb4dde4dbeef
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "5Yo3XXnrQpjc20u0ybrf2g",
"user_id": "4y5K5trZocEAQYkesWlk7M",
"service_id": null,
"name": "my_token",
"scope": "api-key",
"created_at": "2016-06-22T03:19:48+00:00"
"expires_at": "2016-07-28T19:24:50+00:00",
}
]

GET /tokens/self

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

Authentication

API token

Request Example
GET /tokens/self
Fastly-Key: d3cafb4dde4dbeef
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "5Yo3XXnrQpjc20u0ybrf2g",
"user_id": "4y5K5trZocEAQYkesWlk7M",
"service_id": null,
"name": "my_token",
"scope": "api-key",
"created_at": "2016-06-22T03:19:48+00:00"
"expires_at": "2016-07-28T19:24:50+00:00",
}

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
Content-Type: application/x-www-form-urlencoded
Accept: application/json
"username=me@example.com&password=secret&service_id=5VqE6MOOy1QFJbgmCK41pY&expires_at=2016-07-28T19:24:50+00:00"
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "5Yo3XXnrQpjc20u0ybrf2g",
"access_token": "d3cafb4dde4dbeef",
"user_id": "4y5K5trZocEAQYkesWlk7M",
"service_id": "5VqE6MOOy1QFJbgmCK41pY",
"name": "my_token",
"scope": "api-key",
"expires_at": "2016-07-28T19:24:50+00:00",
"created_at": "2016-06-22T03:19:48+00:00"
}

DELETE /tokens/self

Revoke a token that is used to authenticate the request.

Authentication

API token

Request Example
DELETE /tokens/self
Fastly-Key: d3cafb4dde4dbeef
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

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

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

An HTTP 400 response with a JSON body containing an error code is returned on error.

Code Description
invalid_grant Supplied username/password combination is not correct
invalid_request The username/password combination is not supplied. If you're using cURL on the command line, make sure the options are correct.
account_locked Your account is locked.
2fa.verify Your 2FA token is not supplied or is expired.

GET /tokens

GET /tokens/self

DELETE /tokens/:token_id

DELETE /tokens/self

API key

Include your API key as a Fastly-Key header. For example:

GET /some/path
Host: https://api.fastly.com
Fastly-Key: d3cafb4dde4dbeef

As a simplified cURL example, it would look like this:

curl -H "Fastly-Key: d3cafb4dde4dbeef" https://api.fastly.com/some/path

Session

Some API endpoints allow for session authentication. This is similar to how your web browser sends information back and forth to the Fastly Application.

To gain a session token, first POST your user and password the /login endpoint with the parameters user and password. For example:

POST /login
Host: https://api.fastly.com
Content-Type: application/x-www-form-urlencoded
user=testowner@example.com&password=superSecretPassword

As a simplified cURL example:

curl -d "user=testowner@example.com&password=superSecretPassword" https://api.fastly.com/login

This request will return a session ident in the fastly.session value in the form of a standard cookie format header.

Most utilities and frameworks include some facility for storing returned cookies, and for sending them with later requests.