# Personal access tokens

> Create a personal access token, choose its scope and lifetime, and rotate or revoke it; the credential the REST API, the MCP server, the agent API and aiopsctl use.

_How-to · Updated 2026-10-26 · Describes release 0.1.164_

**Before you start.** Any workspace membership can create a token; it acts as you, capped by its scope and by your workspace role ([Concepts you need first](/help/rest-api.md#concepts-you-need-first)). The same token serves the [REST API](/help/rest-api.md), the [MCP server](/help/mcp-server.md), the [agent API](/help/agent-api.md) and [aiopsctl](/help/aiopsctl.md); the webhook token is a different credential ([Create the webhook token](/help/setup-alert-sources.md#create-the-webhook-token)).

## Personal access tokens {#personal-access-tokens}

### What a token is

A personal access token is a per-user credential of the form `ntp_<random>`. Only its SHA-256 hash and the last four characters are stored. It carries a forced expiry (90 days when created from the portal, one year maximum) and can be revoked at any time. Every token belongs to exactly one user; you can only see and revoke your own.

### Create a token

Requires: any tenant membership. Tokens are per-user, not per-tenant, so no extra permission applies.

1. Open **Settings · Data in → Alert intake & tokens** (`/portal/tokens`).
2. Select **New API token**. The dialog states the consequence: "The token acts as you, capped by its scope. It is shown exactly once."
3. Enter a **Name**. This is a label only, for example `ci-benchmarks`. **Create token** stays disabled while it is blank.
4. Choose a **Scope**. The dialog defaults to `read`.
5. Select **Create token**.
6. Copy the value with the **Copy API token** button and store it in your secret manager.

You should see an **API token created** card at the top of the page headed "Copy it now — it is never shown again", and a new row in the **API tokens** list carrying the scope badge and `never used`.

If you navigate away before copying, the token is unrecoverable. Revoke it and create another.

### Choose the right scope

| Scope | Grants on MCP | Typical holder |
|---|---|---|
| `read` | ordinary GET operations plus `chat_ask`, `lake_query` and `test_tenant_idp`; excludes protected credential/admin routes | dashboards, evidence collection and permitted read queries |
| `write` | read access plus tenant writes and execution previews your role permits; excludes protected credential/admin routes | on-call approvals, onboarding scripts, evaluation harnesses |
| `admin` | write access plus protected credential operations and every change that gives another person a login: member invites, adding, re-roling or removing members, the workspace identity provider and an organization administrator's workspace staffing; every `/mcp/admin` tool also requires a superadmin account | users managing tokens or members, and platform operators |

Scope cannot be edited after creation. To change it, create a new token and revoke the old one.

Token scope and workspace permission are separate gates. Connection tests and execution previews require a write or admin token under the current REST scope policy. Chat, lake queries and IdP tests accept a read token but still require their workspace permissions. Some GET report exports can save artifacts under their normal permissions; `read` does not mean nothing can be recorded. The MCP `readOnlyHint` describes an operation and is not a token-scope grant. Every platform-admin MCP tool requires an admin-scope token and a superadmin account.

### Choose a lifetime other than 90 days

The portal has no expiry field: it always mints 90 days. To pick a different lifetime, create the token over REST. `POST /me/tokens` accepts `expires_days` between 1 and 365, and needs an existing valid token (or your browser session) as the credential.

```bash
curl -X POST https://aiops.example.com/me/tokens \
  -H "Authorization: Bearer $EXISTING_PAT" -H "Content-Type: application/json" \
  -d '{"name":"ci-benchmarks","scope":"write","expires_days":365}'
```

The response is `201` and carries the raw `token` once, plus the row as it appears in the list. You should see the new token in **API tokens** with the expiry you asked for.

### Rotate and revoke

Rotation is create-then-revoke. Because tokens are independent rows, both work during the overlap, so there is no downtime.

1. Create the replacement token with the same scope and a name that identifies the system holding it.
2. Deploy it to that system and confirm the system is working.
3. Return to **Alert intake & tokens**.
4. Select the trash button on the predecessor's row (aria-label **Revoke token <name>**), then **Revoke token** in the **Revoke API token** dialog.

You should see the old row remain in the list, marked `revoked` and without a trash button. Revocation takes effect on the next request that uses it.

Three things about revocation that surprise people:

- **Revocation cannot be undone.** The dialog says so before you confirm: anything using the token stops authenticating, and a revoked token cannot be restored. Create a new token instead.
- **A revoked token stays in the list**, marked `revoked`; an expired token is marked `expired`. Neither row offers the trash button. Revocation is a timestamp kept for audit. The name is your only handle, so name every token after the system that holds it.
- **Revoking a member's tenant role also revokes what their tokens can do**, immediately, because permission is evaluated per call. The token row itself survives until revoked separately.

Each row shows the scope badge and either `last used <date and time>` or `never used`, followed on a live token by `· expires <date>`. That is the quickest way to identify a token nobody ever deployed. The `last used` stamp is throttled to roughly one write per minute, so a burst of calls does not show as a burst of updates.

## Next steps {#next-steps}

- [REST API](/help/rest-api.md) — find your tenant id and make the first call.
- [MCP server](/help/mcp-server.md) — **Connect your agent** mints a token for your client as part of its setup.
- [Members and roles](/help/members-and-roles.md) — the role that caps what a token can do.