---
title: Automation Tokens
summary: >-
  Automation tokens differ from other token types because they are not tied to a
  specific person and therefore are not subject to the lifecycle of such
  accounts. Automation tokens are sometimes also called "service accounts". They
  are designed for API automation use-cases such as continuous integration,
  deployment pipelines, or automation scripts. For more information about
  authentication tokens, review the <a
  href="https://www.fastly.com/documentation/reference/api/auth-tokens/user/">Authentication
  token</a> documentation.
url: https://www.fastly.com/documentation/reference/api/auth-tokens/automation
---

Automation Tokens are a type of authentication token used to allow non-human clients, such as continuous integration and build systems, to perform actions via the Fastly API. Any API endpoint that requires token authentication will accept an automation token, as long as it has the required scope.

However, automation tokens can only be created by human users with the role of `superuser`, presenting a [user token](https://www.fastly.com/documentation/reference/api/auth-tokens/user/).

### Limitations

Automation tokens currently have the following limitations:

- Only users with the role of superuser can create automation tokens and must be in [sudo mode](https://www.fastly.com/documentation/reference/api/utils/sudo/).
- All [user token limitations](https://www.fastly.com/documentation/reference/api/auth-tokens/user/#limitations) also apply to automation tokens.
- Users cannot create automation token if their account has [force SSO](https://www.fastly.com/documentation/guides/account-info/user-access-and-control/setting-up-single-sign-on-sso/#requiring-sso-for-your-organization) or [MFA enabled](https://www.fastly.com/documentation/guides/account-info/account-management/managing-two-factor-authentication/#enabling-two-factor-authentication).

### Multiple roles

Automation tokens can be assigned multiple roles, allowing fine-grained control over what the token can access. When creating a token with multiple roles, use the `roles` array field instead of the `role` string field.

You can also control which services and workspaces the token can access:

| Field              | Description                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `roles`            | Array of role IDs to assign to the token. Get available IDs from [GET /roles](https://www.fastly.com/documentation/reference/api/account/roles/).            |
| `limit_services`   | When `true`, restricts the token to only the services specified in the `services` array. When `false` (default), the token has access to all services.       |
| `limit_workspaces` | When `true` (default), restricts the token to only the workspaces specified in the `workspaces` array. When `false`, the token has access to all workspaces. |
| `services`         | Array of service IDs the token can access. Only applies when `limit_services` is `true`.                                                                     |
| `workspaces`       | Array of workspace IDs the token can access. Only applies to roles that support workspace access (such as Next-Gen WAF roles).                               |

**Service access behavior:**

| `limit_services`  | `services` array | Result                                                  |
| ----------------- | ---------------- | ------------------------------------------------------- |
| `false` (default) | empty            | Full access to all services                             |
| `true`            | empty            | No service access (useful for Next-Gen WAF-only tokens) |
| `true`            | populated        | Access to specified services only                       |

**Workspace access behavior:**

| `limit_workspaces` | `workspaces` array | Result                                                       |
| ------------------ | ------------------ | ------------------------------------------------------------ |
| `false`            | empty              | Full access to all workspaces                                |
| `true` (default)   | empty              | No workspace access (error for non-owner Next-Gen WAF roles) |
| `true`             | populated          | Access to specified workspaces only                          |

### Error states

The following error states may be returned from token API requests.

#### POST /automation-tokens

- A response with a JSON body containing an error code is returned on error. The error codes match those defined in [Authentication Tokens](https://www.fastly.com/documentation/reference/api/auth-tokens/user/#error-states).

#### GET /automation-tokens

- An HTTP 401 response is returned on an expired token.
- An HTTP 403 response is returned on an invalid access token.

#### GET /automation-tokens/:token_id

- An HTTP 401 response is returned on an expired token.
- An HTTP 403 response is returned on an invalid access token.

#### GET /automation-tokens/:token_id/services

- An HTTP 401 response is returned on an expired token.
- An HTTP 403 response is returned on an invalid access token.

#### DELETE /automation-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.

#### GET /automation-tokens/:token_id/workspaces

- An HTTP 401 Unauthorized response is returned on an expired token.
- An HTTP 403 Forbidden response is returned on an invalid access token.
- An HTTP 404 Not Found response is returned if the token does not exist.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `expires_at` | string | A UTC timestamp of when the token expires. |
| `limit_services` | boolean | When <code>true</code>, the token is restricted to only the services in the <code>services</code> array. When <code>false</code>, the token has access to all services. |
| `limit_workspaces` | boolean | When <code>true</code>, the token is restricted to only the workspaces in the <code>workspaces</code> array. When <code>false</code>, the token has access to all workspaces. Only applies to roles that support workspace access. |
| `name` | string | The name of the token. |
| `role` | string | The primary role on the token. For tokens with multiple roles, this returns the highest-priority role for backwards compatibility. |
| `roles` | array | All roles assigned to the token. Each role includes an <code>id</code> and <code>name</code>. |
| `scope` | string | A space-delimited list of authorization scope. |
| `services` | array | The service IDs of the services the token has access to. Empty when <code>limit_services</code> is <code>false</code> (full access) or when the token has no service access. |
| `workspaces` | array | The workspace IDs of the workspaces the token has access to. Returns an empty array for tokens without workspace access. |
| `tls_access` | boolean | Indicates whether TLS access is enabled for the token. Only applicable when using the single-role <code>role</code> field. For tokens with multiple roles, assign TLS roles (<code>tls_admin</code> or <code>tls_viewer</code>) via the <code>roles</code> field instead. |
| `created_at` | string | A UTC timestamp of when the token was created. (Read-only) |
| `customer_id` | string | Alphanumeric string identifying the customer. (Read-only) |
| `id` | string | Alphanumeric string identifying a token. (Read-only) |
| `last_used_at` | string | A UTC timestamp of when the token was last used. (Read-only) |
| `user_agent` | string | The User-Agent header of the client that last used the token. |
| `user_id` | string | Alphanumeric string identifying the user. (Read-only) |
| `errors` | array |  |
| `ip` | string | The IP address of the client that last used the token. |
| `limit` | integer | Number of results requested. |
| `next_cursor` | string | Cursor for the next page. Empty string when there are no more results. |
| `previous_cursor` | string | Cursor for the previous page. Empty string when on the first page. |
| `meta` | object |  |

## API endpoints

### List Customer Automation Tokens

**GET** `/automation-tokens`

Lists all automation tokens for a customer.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `page` | integer | query | No |  |
| `per_page` | integer | query | No |  |

### Create Automation Token

**POST** `/automation-tokens`

Creates a new automation token.

### Retrieve an Automation Token by ID

**GET** `/automation-tokens/{id}`

Retrieves an automation token by ID.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `id` | string | path | Yes |  |

### Revoke an Automation Token by ID

**DELETE** `/automation-tokens/{id}`

Revoke an automation token by ID.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `id` | string | path | Yes |  |

### List Automation Token Services

**GET** `/automation-tokens/{id}/services`

List of services associated with the automation token.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `id` | string | path | Yes |  |
| `page` | integer | query | No |  |
| `per_page` | integer | query | No |  |

### List Automation Token Workspaces

**GET** `/automation-tokens/{id}/workspaces`

Lists the Next-Gen WAF workspaces accessible by an automation token. Only applicable for tokens with roles that support workspace access (such as Next-Gen WAF roles).

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cursor` | string | query | No | Pagination cursor from a previous response. Pass the <code>next_cursor</code> value to retrieve the next page, or <code>previous_cursor</code> to go back. |
| `id` | string | path | Yes | The alphanumeric string identifying the automation token. |
| `limit` | integer | query | No | Maximum number of workspaces to return per page. |
