Authentication

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 account and services. You can limit the capabilities of tokens using a scope. For example, the purge_select scope will limit a token to only be able to purge by URL and surrogate keys. The default global scope will grant the token access to all the service and account-level capabilities of the user that created the token. You can optionally restrict the service-level access of a token to one or more services. However, for a token with the global or global:read scope, limiting service access does not limit access to non-service related endpoints. 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.

1
2
3
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. Limiting a token's service access does not prevent the token from accessing non-service related endpoints.

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 optionally restrict the service-level access of a token to one or more services. Do this by specifying an array in the POST /tokens action (e.g., services[]=id1&services[]=id2).

Note that limiting service access is designed to be used with the purge-all and purge-select scopes. A service-limited token with the global or global:read scopes will still be able to access non-service related endpoints. All service-limited tokens are prevented from modifying service authorizations, inviting new users to the account, and creating and modifying users.

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

To delete a user who has active API tokens associated with their account, you must first revoke the user's API tokens.

Limitations

API tokens currently have the following limitations:

API reference

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.