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_TOKENTwo-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/tokensFastly-OTP: 123456username=youremail@example.com&password=PASSWORDScopes
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
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.