Managing account-level API tokens

Account-level API tokens are unique security credentials that let automation systems act on behalf of your company account. Deployment pipelines, continuous integration systems, and other non-human clients use them to authenticate to Fastly and perform specific operations via the Fastly API. Within the Fastly control panel, you'll see them referred to as "automation tokens." This guide covers how to create, view, and delete them. You'll also find information about token scopes, limitations, and best practices for managing them safely.

Creating an automation token

Only users assigned the superuser role can create automation tokens. Creating an automation token requires sudo mode.

To create an automation tokens:

1. Log in to the Fastly control panel.

2. Go to Account > API tokens > Personal tokens.

3. Click Create token.

4. When prompted, enter your password to re-authenticate your permissions.

   

5. Fill out the Create a Token fields as follows:

   • In the Name field, enter a descriptive name for the token that indicates how or where it will be used.
   • From the Type options, select Automation token.
   • From the Role options, select the user role that will assign the appropriate access permissions to the API token. Our guide to configuring user roles and permissions provides more information.
   • (Optional) Select TLS management to grant the token the ability to modify TLS configurations across all services, including TLS certificates and domains.
   • From the Scope options, select one or more checkboxes to limit the token's access to a specific scope. Only the Scope options applicable to the selected role will be selectable.
   • From the Access options, select either all services or limit the token's access to a specific service or group of services by selecting them from the Search or select service menu.
   • From the Expiration options, set the token expiration timeframe. By default the control panel will set the expiration date to 90 days from the date on which you create it. You can, however, set a token to never expire or you can select a specific date on which it expires.

   IMPORTANT: After a token expires, using it for any request will return an HTTP 401 response.

6. Click Create Token. A new token and its creation notification appears.

7. Click the clipboard to copy the API token string so you can store it in a safe, secret location.

   WARNING: This is the only time the token string will be visible. Be sure to immediately copy it and store it in a safe location. It will never be visible again.

8. Click Okay.

Viewing account-level tokens

To view the account-level tokens for your company account:

1. Log in to the Fastly control panel.
2. Go to Account > API tokens > Account tokens. The Account Tokens page appears with a list of tokens associated with your organization's Fastly account.

Deleting an account-level token

To delete an account-level token:

1. Log in to the Fastly control panel.
2. Go to Account > API tokens > Account tokens.
3. Find the token you want to delete and click the trash .
4. Click Delete to permanently delete the token.

Best practices

• Keep it secret. Keep it safe. Anyone with your API token can add and delete data as you, so treat it with the same care as a password.
• Use descriptive names. Use enough words in the name field to make the token's purpose clear months later. Something like "GitLab CI deployment token for staging" is more useful than "test token."
• Store tokens securely. Store tokens in a password manager, secret vault, or environment variables. Never commit them to a code repository or store them in plain text config files. You can only copy a token's string once, at creation, so capture it immediately.
• Use the least privilege necessary. Restrict a token's scope, service access, and expiration to the minimum it needs. This limits the damage if the token is ever compromised. For more information, review the principle of least privilege.
• Use different tokens for different purposes. Create separate tokens for different integrations and applications rather than sharing one token across many uses. When something changes or a token is compromised, you can revoke the affected one without breaking everything else.
• Rotate tokens periodically. Replace long-lived tokens on a regular schedule. Even if you don't know a token has been compromised, rotation limits how long a leaked token would remain useful.
• Monitor for unexpected activity. Watch the event log for token activity you don't recognize. If a token starts doing things you didn't do, revoke it immediately.

Token scopes

You can limit the capabilities of API tokens by specifying the scope of their service-related activities. Specifically, you can allow or limit API tokens as follows:

• Global API access (global) allows the token full control over a service with access to all API endpoints, including purging.
• Purge full cache (purge_all) allows the token purging ability for an entire service via a purge_all API request.
• Purge select content (purge_select) allows the token purging ability via Surrogate-Key and URL but does not include the ability to purge all cache.
• Read-only access (global:read) allows the token read-only access to account information, configuration, and stats.

Limitations and considerations

When managing and using automation tokens, keep in mind the following:

• Superuser-created. Only users assigned the superuser role can create automation tokens.
• Sudo mode required. Creating an automation token requires sudo mode, which prompts for password re-authentication.
• SSO and 2FA API restriction. Automation tokens cannot be created via API if the company account has force SSO or company-wide two-factor authentication enabled. Because automation token credentials are programmatic rather than interactive, their creation must go through the Fastly control panel where the creator's identity can be verified.
• Immutable. API tokens can only be created, viewed, and deleted. They cannot be edited or updated.
• Automatic expiration. Unused tokens do not last forever. API tokens that remain unused for two years are automatically deleted even if they have been set to never expire.
• No Next-Gen WAF support. Automation tokens are not supported for Next-Gen WAF features.

Legacy API credentials

If you created an account with Fastly 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 an API token with a global scope and access to all of your services. It was assigned to a newly created, synthetic user with the name Global API Token.

Related content

• Managing personal API tokens
• Automation tokens API documentation