Using API tokens

API tokens are unique security credentials that allow human users and automated systems to prove their identity to Fastly, thereby indicating they can be trusted to access restricted resources and perform specific, restricted operations via the Fastly API. Use the API tokens page to add, view, and delete API tokens.

About API tokens

There are two types of API tokens: user tokens and automation tokens. Each type can optionally have their capabilities limited by controlling the specific scope of their activities.

Token types

There are two types of API tokens. Your ability to manage them is based on the roles and permissions you have been assigned.

  • Automation tokens. Automation tokens provide security credentials for non-human clients (e.g., continuous integration and build systems) that need to conduct automated API activities like continuous integrations, deployment pipelines, and routinely scripted tasks. Automation tokens may sometimes be referred to as "account tokens" or "service account tokens."

    Only superusers can create automation tokens. These tokens are not tied to a specific human user and therefore can remain active indefinitely. They only appear as part of a company's profile settings and can only be managed by human users assigned the role of superuser.

  • User tokens. User tokens provide security credentials for API activities initiated by human users. They are associated with a specific human and are only active for the lifetime of that user's account. User tokens may sometimes be referred to as "personal tokens" or "personal API tokens."

    Anyone can create and view their own user tokens. These tokens carry the same permissions as the user who would be performing account-based actions via the API. For example, if you are a billing user, then your user token will only allow you to perform the capabilities assigned to the billing role. When a user's account is deleted, active API tokens must be revoked.

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 best practices

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

  • API tokens can only be created, viewed, and deleted. They cannot be edited or updated.
  • Each user is limited to 100 active API tokens. Deleted and expired tokens don't count against the limit.
  • 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.
  • Your role and its permissions change what you see in the event log. The user roles and permissions assigned to you control exactly what you can and can't view in the event log when API token work appears there. Specifically, if you've been assigned the user role, you can only see events from your own actions. If you've been assigned the engineer role, you can see all events related to your own actions plus all the actions on services to which you've been granted access.

When creating API 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 can minimize the risk of damage if security credentials are somehow compromised. For more information, review the principle of least privilege.

Creating API tokens

To create an API token, follow the steps below:

  1. Log in to the Fastly web interface and select Account from the account menu. Your account information appears.
    IMPORTANT

    If you're creating a user token, be sure you're creating tokens for the right account. If you've been invited as a user on multiple accounts, you'll need to switch to the appropriate account first.

  2. Click API tokens.

  3. Click Create token.

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

    create a token page

  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, optionally select the type of API token to create: User token or Automation token. Only superusers have the ability to create automation tokens. If you select Automation token, controls to specify the user role for that token appear.
    • From the Role options, select the user role that will assign the appropriate access permissions to the API token. Available options are Engineer, User, and Billing. 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. Our guide to configuring user roles and permissions provides more information.
    • 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 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.
    TIP

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

  6. Click Create Token to create the new token. A new token and its creation notification appears. This is the credential you'll use to authenticate via the Fastly API. You may use the same token for multiple applications.

  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 your API 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 API tokens

To view API tokens, follow these steps.

Viewing user tokens

To view your personal user tokens, follow these steps:

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

    personal user token management page

Viewing account tokens

If you've been assigned the role of superuser, view account tokens using these steps:

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

    account token management page

Deleting API tokens

WARNING

Deleting an API token will break any integration actively using that credential.

To delete user or automation tokens, follow these steps.

Deleting user tokens

To delete a user token, follow these steps:

  1. Log in to the Fastly web interface and select Account from the account menu. Your account information appears.
  2. Click API tokens.
  3. Find the token you want to delete and click the trash.
  4. Click Delete to permanently delete the user token.

Deleting account tokens

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

  1. Log in to the Fastly web interface and select Account from the account menu. Your account information appears.
  2. Click Account tokens.
  3. Find the token you want to delete and click the trash.
  4. Click Delete to permanently delete the token.

Legacy API credentials

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. It was assigned to a newly created, synthetic user with the name Global API Token.

global API token user

Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.