--- title: User tokens summary: >- An API Token is used to identify who is making the API call. Users can create multiple tokens to suit their needs. url: https://www.fastly.com/documentation/reference/api/auth-tokens/user --- An API Token is used to identify who is making the API call. Users can create multiple tokens to suit their needs. API tokens are unique authentication identifiers that you can create for the users 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 of the same 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. For tokens that are intended for use by automated systems, use an [automation token](https://www.fastly.com/documentation/reference/api/auth-tokens/automation/) instead. ## Overview Most API endpoints require a token, which should be included in the `Fastly-Key` HTTP header: ```http Fastly-Key: YOUR_FASTLY_TOKEN ``` ### Two-factor authentication API tokens support [two-factor authentication](https://www.fastly.com/documentation/guides/account-info/account-management/managing-two-factor-authentication/). Send the generated one-time password via the Fastly-OTP header when creating a token, as shown below. ```http POST https://api.fastly.com/tokens Fastly-OTP: 123456 username=youremail@example.com&password=PASSWORD ``` ### Scopes Scopes can be used to limit a token's capabilities. The following scopes are currently supported: - **`global`**: 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](https://www.fastly.com/documentation/reference/api/purging#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](https://en.wikipedia.org/wiki/ISO_8601) format (e.g., `2016-07-28T19:24:50+00:00`). ### Deleting a user with active tokens To [delete a user](https://www.fastly.com/documentation/guides/account-info/user-access-and-control/adding-and-deleting-user-accounts/#deleting-account-users) who has active API tokens associated with their account, you must first [revoke the user's API tokens](https://www.fastly.com/documentation/reference/api/auth-tokens/user#revoke-token). ### 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](https://www.fastly.com/documentation/guides/account-info/user-access-and-control/configuring-user-roles-and-permissions/) 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 | Field | Type | Description | |-------|------|-------------| | `name` | string | Name of the token. | | `scope` | string | Space-delimited list of authorization scope. | | `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. (Read-only) | | `access_token` | string | The alphanumeric string for accessing the API (only available on token creation). | | `created_at` | string | Time-stamp (UTC) of when the token was created. (Read-only) | | `deleted_at` | string | Date and time in ISO 8601 format. (Read-only) | | `expires_at` | string | Time-stamp (UTC) of when the token will expire (optional). | | `id` | string | Alphanumeric string identifying a token. (Read-only) | | `ip` | string | IP Address of the client that last used the token. | | `last_used_at` | string | Time-stamp (UTC) of when the token was last used. (Read-only) | | `updated_at` | string | Date and time in ISO 8601 format. (Read-only) | | `user_agent` | string | User-Agent header of the client that last used the token. | | `user_id` | string | Alphanumeric string identifying the user. (Read-only) | ## API endpoints ### List tokens for the authenticated user **GET** `/tokens` List all tokens belonging to the authenticated user. ### Create a token **POST** `/tokens` Create an API token. If two-factor authentication is enabled for your account, review the instructions for including a one-time password in the request. ### Revoke multiple tokens **DELETE** `/tokens` Revoke Tokens in bulk format. Users may only revoke their own tokens. Superusers may revoke tokens of others. ### List tokens for a customer **GET** `/customer/{customer_id}/tokens` List all tokens belonging to a specific customer. **Parameters:** | Name | Type | In | Required | Description | |------|------|----|---------|--------------| | `customer_id` | string | path | Yes | Alphanumeric string identifying the customer. | ### Get the current token **GET** `/tokens/self` Get a single token based on the access_token used in the request. ### Revoke the current token **DELETE** `/tokens/self` Revoke a token that is used to authenticate the request. ### Get a token **GET** `/tokens/{token_id}` Get a single token by its id. **Parameters:** | Name | Type | In | Required | Description | |------|------|----|---------|--------------| | `token_id` | string | path | Yes | Alphanumeric string identifying a token. | ### Revoke a token **DELETE** `/tokens/{token_id}` Revoke a specific token by its id. **Parameters:** | Name | Type | In | Required | Description | |------|------|----|---------|--------------| | `token_id` | string | path | Yes | Alphanumeric string identifying a token. | ## 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 an expired token. - An HTTP 403 response is returned on an invalid access token. #### GET /tokens/self - An HTTP 401 response is returned on an expired token. - An HTTP 403 response is returned on an invalid access token. #### DELETE /tokens/:token_id - An HTTP 400 response is returned on a revocation error. - An HTTP 401 response is returned on an expired token. - An HTTP 403 response is returned on an invalid access token. - An HTTP 404 response is returned on a failed token lookup. #### DELETE /tokens/self - An HTTP 400 response is returned on a revocation error. - An HTTP 401 response is returned on an expired token. - An HTTP 403 response is returned on an invalid access token.