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.

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:

global: This is the default scope covering all supported capabilities. This scope grants the same access level as legacy API keys.

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

Limitations

Tokens are always associated with the user who created them. This cannot be updated.

When you generate a new token, you should store it in a safe place and keep it secret. For security reasons, you won't be able to retrieve the token later.

There is a limit of 100 tokens per user. Deleted and expired tokens don't count against the limit.

Tokens carry the same permission model as the user. For example, if you are a billing user, then your token will only allow you to perform the capabilities of the billing role.

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

Response Example

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

An HTTP 401 response is returned on expired token.

An HTTP 403 response is returned on invalid access token.

GET /tokens/self

An HTTP 401 response is returned on expired token.

An HTTP 403 response is returned on invalid access token.

DELETE /tokens/:token_id

An HTTP 400 response is returned on revocation error.

An HTTP 401 response is returned on expired token.

An HTTP 403 response is returned on invalid access token.

An HTTP 404 response is returned on failed token lookup.

DELETE /tokens/self

An HTTP 400 response is returned on revocation error.

An HTTP 401 response is returned on expired token.

An HTTP 403 response is returned on invalid access token.

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.