> For the complete documentation index, see [llms.txt](https://docs.perfectscale.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perfectscale.io/administration/api-and-cluster-tokens.md).

# API and cluster tokens

Create and manage the tokens that let scripts, the PerfectScale CLI and cluster agents authenticate with PerfectScale

PerfectScale uses two kinds of tokens. Both are managed in **Settings**.

* **API tokens** let scripts, the [PerfectScale CLI](https://docs.perfectscale.io/product-overview/perfectscale-agent-skill.md) and AI agents call the [Public API](https://docs.perfectscale.io/api/public-api.md) on behalf of your organization.
* **Cluster tokens** are used by the PerfectScale agent in each cluster to authenticate with PerfectScale. Each cluster authenticates with its own token.

## Open the token pages

1. In the left navigation, click **More**, then **Settings**.
2. Open **API Tokens** or **Cluster Tokens**.

## API tokens

The **API Tokens** tab lists the tokens of your organization with their name, token ID, roles, creator, creation date, last use and expiration date. You can filter the list by name, token ID and creator.

![The API Tokens tab in Settings](https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FQfyML0ZeUfMxQrZLECCG%2Fapi-tokens-list.jpg?alt=media\&token=16aa1af7-b1a8-4190-bea8-54d886ab6d2d)

Every user can open this page, create tokens and delete the tokens they created. Organization admins can delete any token. A token with the **No owner** badge has no known creator.

### Create a token

1. In **Settings**, open **API Tokens** and click **Create Token**.
2. Enter a **Name** that tells you what the token is used for, for example `ci-pipeline`.
3. Select the **Roles** of the token.
4. Select the **Expiration**: Never, 30 days, 90 days or 1 year.
5. Click **Create**.

![The Create API Token dialog](https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FoepyLIC8aV2aNXL7KgG7%2Fcreate-api-token-dialog.jpg?alt=media\&token=2b47830d-91fc-469c-a5a5-10974793105a)

PerfectScale shows the **Token ID** and the **Token Secret** once. Copy both before you close the dialog. The secret cannot be retrieved later; if you lose it, delete the token and create a new one.

### Token roles

A token can only have roles that are equal to or lower than your own roles:

| Your role  | Roles you can give to a token |
| ---------- | ----------------------------- |
| Admin      | Admin, Power User, Read Only  |
| Power User | Power User, Read Only         |
| Read Only  | Read Only                     |

A token has the permissions of its roles. A Read Only token can call the Public API `GET` endpoints, but it cannot create, change or delete anything. For tokens that query data, for example with the CLI, use the Read Only role. For more about roles, see [RBAC | Roles and permissions](https://docs.perfectscale.io/administration/rbac-or-roles-and-permissions.md).

### Delete a token

Click **Delete** at the end of the token row and confirm in the dialog. Anything that uses the token can no longer authenticate.

### Use a token with the CLI

Use the token ID and secret to sign in with the PerfectScale CLI:

```bash
pscli auth login --client-id 'YOUR_TOKEN_ID' --client-secret 'YOUR_TOKEN_SECRET'
```

The CLI and its agent skill are described in [PerfectScale agent skill](https://docs.perfectscale.io/product-overview/perfectscale-agent-skill.md). To call the API directly, see [Public API](https://docs.perfectscale.io/api/public-api.md).

## Cluster tokens

The **Cluster Tokens** tab lists the token of each cluster with the cluster name, token ID, age and creation date. Use it to check which token a cluster agent uses. You can filter the list by cluster name and token ID.

![The Cluster Tokens tab in Settings](https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FIZPqvCoPvGm9RZZgISIj%2Fcluster-tokens-list.jpg?alt=media\&token=f47534cd-8751-489a-afbb-096ae621e1e9)

One token can be used by more than one cluster. In that case the list shows the first cluster name and a badge with the number of other clusters, for example `+1`.

To connect a new cluster, see [How to onboard a cluster](https://docs.perfectscale.io/getting-started/how-to-onboard-a-cluster.md).
