Using API tokens

API tokens are unique authentication credentials assigned to individual users. You need to create a token to use the Fastly API. You can use tokens to grant applications restricted access to your Fastly account and services. For example, an engineer user could limit a token to only have access to a single service, and restrict the scope to only allow that token to purge by URL. Every Fastly user can create up to 100 tokens.

There are two places in the web interface where tokens are managed, depending on your user role. The Personal API tokens page allows you to create, view, and delete tokens associated with your personal profile. The Account API tokens page allows superusers to view and delete any of the tokens associated with the organization’s Fastly account.

Limitations and best practices

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

  • Tokens can only be created, viewed, and deleted. They cannot be edited or updated.
  • Each user is limited to 100 active tokens. Deleted and expired tokens don't count against the limit.

When creating tokens, also keep the following best practices in mind:

  • Keep it secret. Keep it safe. When you generate a new token, you should store it in a protected place like a password manager to keep it secret and safe. For security reasons, you will only be able to copy tokens once, at the time of creation. You won't be able to retrieve token strings later.

  • Consider implementing minimal privileges. Limiting a token's service access, controlling its scope, and setting an expiration date restricts that credential's access and can minimize the risk of damage if security credentials are somehow compromised. For more information, review the principle of least privilege.

Creating tokens

To create a token, follow the steps below:

  1. Log in to the Fastly web interface and click the Account link from the user menu. Your account information appears.
  2. Click the Personal API tokens link. The API Tokens page appears.
  3. Click the Create Token button. The Create a Token page appears.

    create a token page

  4. If 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 API token that indicates how or where you will to use the token.
    • In the Service Access area, select a service to restrict the service-level access of the token to one service or optionally switch to All Services to grant the API token access to all services.
    • In the Scope area, select one or more checkboxes to set a token's scope:
      • Global API access (global): Allows access to all endpoints, including purging.
      • Purge full cache (purge_all): Allows purging an entire service via a purge_all API request.
      • Purge select content (purge_select): Allows purging with Surrogate-Key and URL. Does not include the ability to purge all cache.
      • Read-only access (global:read): Allows read-only access to account information, configuration, and stats.
    • In the Expiration area, optionally set the API token to never expire. By default the web interface 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. After a token expires, using it for any request will return an HTTP 401 response.
  6. Click the Create button to create the new API token. The string that comprises the token appears.

This is the credential you'll use to authenticate via the Fastly API. Copy this string to a secure location — it will never be visible again. You may use the same token for multiple applications.

Viewing API tokens

You can view two types of API tokens for your account depending on your assigned role.

Viewing personal API tokens

To view personal API tokens, follow these steps:

  1. Log in to the Fastly web interface and click the Account link from the user menu. Your account information appears.
  2. Click the Personal API tokens link. The API tokens page appears with a list of your personal tokens.

    api token management page

Viewing account API tokens

To view account API tokens as a superuser, follow these steps:

  1. Log in to the Fastly web interface and click the Account link from the user menu. Your account information appears.
  2. Click the Account API tokens link. The Account API tokens page appears with a list of tokens associated with your organization's Fastly account.

    api token management page

Deleting tokens

Deleting personal API tokens

To delete personal API tokens, follow the steps below:

  1. Log in to the Fastly web interface and click the Account link from the user menu. Your account information appears.
  2. Click the Personal API tokens link. The API tokens page appears with a list of your personal tokens.
  3. Find the API token you want to delete and click the trash icon. A warning message appears.
  4. Click the Delete button to permanently delete the API token.

Deleting account API tokens

To delete an account API token or to revoke another user's API token as a superuser, follow the steps below:

  1. Log in to the Fastly web interface and click the Account link from the user menu. Your account information appears.
  2. Click the Account API tokens link. The Account API tokens page appears with a list of tokens associated with your organization's Fastly account.
  3. Find the token you want to delete and click the trash icon. A warning message appears.
  4. Click the Delete button to permanently delete the token.

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

global API token user

Back to Top