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). The same token serves the REST API, the MCP server, the agent API and aiopsctl; the webhook token is a different credential (Create the webhook token).

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.

Open Settings · Data in → Alert intake & tokens (/portal/tokens).
Select New API token. The dialog states the consequence: "The token acts as you, capped by its scope. It is shown exactly once."
Enter a Name. This is a label only, for example ci-benchmarks. Create token stays disabled while it is blank.
Choose a Scope. The dialog defaults to read.
Select Create token.
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.

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.

Create the replacement token with the same scope and a name that identifies the system holding it.
Deploy it to that system and confirm the system is working.
Return to Alert intake & tokens.
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

REST API — find your tenant id and make the first call.
MCP server — Connect your agent mints a token for your client as part of its setup.
Members and roles — the role that caps what a token can do.