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/tokensFastly-OTP: 123456username=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 | Alphanumeric string identifying a token. |
user_id | string | Alphanumeric string identifying the 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. |
name | string | Name of the token. |
scope | string | Space-delimited list of authorization scope. One or more of:
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. |
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. |
access_token | string | The alphanumeric string for accessing the API (only available on token creation). |
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.