Authentication 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 (and only 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 specific 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.

Most API endpoints require a token, which should be included in the Fastly-Key HTTP header:

Fastly-Key: YOUR_FASTLY_TOKEN

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

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.
purge_select: Allows purging with surrogate key and URL. Disallows purging with purge-all.
purge_all: Allows purging an entire service via purge_all.
global:read: Allows read-only access to account information, configuration, and stats.

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

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:

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.

Data model

`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_used_at`	String	(read-only) 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.

Endpoints

List tokens for the authenticated user

GET/tokens

List tokens for a customer

GET/customer/id/tokens

Get the current token

GET/tokens/self

Create a token

POST/tokens

Revoke the current token

DELETE/tokens/self

Revoke a token

DELETE/tokens/id

Revoke multiple tokens

DELETE/tokens

Error states

The following error states may be returned from token API requests:

POST /tokens

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

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

User contributed notes

We welcome comments that add use cases, ideas, tips, and caveats. All comments will be moderated before publication. To post support questions, visit our support center and we'll find you the help you need.