# Create an API token

Generate workspace tokens from the UI, store the secret, set expiration, and revoke tokens you no longer use.

API tokens let scripts, services, jobs, and integrations call the Metrics API without signing in as an interactive user.

Tokens are scoped to the current workspace. Create them from the workspace where the token should read or write data. They use workspace roles, so they can access workspace resources such as metrics, dashboards, alarms, notification channels, and role-managed workspace APIs.

Tokens are not account sessions. They cannot perform account-specific actions such as changing account settings, selecting workspaces, or inviting workspace members.

## Create a token in the UI

Open **API tokens** from the main menu.

Use the **Create access token** form:

1. Enter a descriptive name, such as `metrics-importer` or `dashboard-refresh`.
2. Select the role the token should use.
3. Choose an expiration period.
4. Select **Generate**.

The app shows the token secret once. Store it immediately in your secret manager, deployment environment, or local development configuration. After you leave the page, the secret cannot be shown again.

For a least-privilege token, create a custom role first, then select that role when generating the token.

## Use the token

Send the token as a bearer token when calling the API:

```bash
curl -X POST "$METRICS_API_URL/v1/metrics/request_count" \
  -H "Authorization: Bearer $METRICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "timestamp": 1779433200000,
        "value": 1
      }
    ]
  }'
```

Use a different token for each service or job. Separate tokens make it easier to rotate one integration without interrupting others.

For example, use one token for a metrics ingester and another for a dashboard export job. If one secret leaks, you can revoke only that integration.

## Review existing tokens

The tokens page lists existing tokens with:

- the token name;
- assigned role;
- token ID;
- creation time;
- last-used time;
- expiration time.

The secret value is not listed. If a token secret is lost, revoke it and create a replacement.

## Revoke a token

Open **API tokens**, find the token, then select **Revoke**.

The API instance that handles the revocation rejects the token immediately. In a multi-replica deployment, another API instance may continue accepting a cached token for up to about 30 seconds. Allow for that propagation window when responding to a compromised secret.

## Change a token role

Open **API tokens**, find the token, choose a different role, then save the change. The token secret stays the same. The handling API instance applies the new role immediately; another API replica may use the previous cached role for up to about 30 seconds.

Through the API, send `PUT /v1/auth/tokens/{tokenId}` with a `role` value. The caller must be able to update that token, read the selected role, and already hold every permission granted by the selected role.

## Role-scoped tokens

Roles define what a token can do inside the workspace. Built-in roles are available, and you can create custom roles from the **Roles** page using the policy dropdowns.

The UI requires a role for every new token. You can also create role-scoped tokens through the API by passing the `role` field to `POST /v1/auth/tokens`.

```bash
curl -X POST "$METRICS_API_URL/v1/auth/tokens" \
  -H "Authorization: Bearer $METRICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "metrics-writer",
    "expiresInDays": 30,
    "role": "Admin"
}'
```

Prefer a custom least-privilege role for production automation. Use broad roles only when the integration genuinely needs broad workspace access.

Role policies only cover workspace-specific actions. Account-specific actions are intentionally unavailable to workspace roles and API tokens. For example, workspace invitations are owner-only account actions, not token permissions.