API tokens

An API token lets a program -- a script, a CI job, an AI agent -- use the API as a person with the same scopes could, including making and revoking other tokens when it holds tokens:write. Send it as Authorization: Bearer us_live_.... A token belongs to the workspace it was made in; it never needs (or accepts) a workspace header.

Shown once. The response that creates a token is the only time it is shown; UsherStats keeps a SHA-256 of it. Lists show the first characters (prefix) so you can tell tokens apart.
Scopes (module:action): analytics:read, sites:read, sites:write, bot:read, bot:write, search:read, search:write, members:read, members:write, tokens:read, tokens:write, billing:read, billing:write, export:read, and account:admin (everything). A call without the scope it needs gets 403 naming the scope.
Site restriction. siteIds limits a token to those sites; every other site is 404 to it, as if it did not exist. A site-restricted token cannot create sites or manage members.
Expiry. expiresAt (ISO 8601) ends it; a revoked or expired token gets 401 saying which.
Never wider than its maker. A token can only be given scopes, sites and a lifetime its creator has. Tokens a person made are revoked when they leave the workspace, and those exceeding a new role when they are demoted.

Route	Scope
`GET /v1/tokens`	`tokens:read`
`POST /v1/tokens`	`tokens:write`
`DELETE /v1/tokens/{id}`	`tokens:write`

The examples assume $US_TOKEN holds a token with account:admin.

Create a token

curl https://api.usherstats.com/v1/tokens \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "nightly report", "scopes": ["sites:read", "analytics:read"], "expiresAt": "2027-01-01T00:00:00Z"}'

The response has the token in token (us_live_ and 40 letters and digits) with "shownOnce": true. Store it now.

Use it

curl https://api.usherstats.com/v1/me \
  -H "Authorization: Bearer $NEW_TOKEN"

/v1/me answers with the token's AuthContext: its workspace, scopes and sites. A call it lacks the scope for:

curl https://api.usherstats.com/v1/tokens \
  -H "Authorization: Bearer $NEW_TOKEN"

List tokens

curl https://api.usherstats.com/v1/tokens \
  -H "Authorization: Bearer $US_TOKEN"

Revoke a token

It stops working at once.

curl -X DELETE https://api.usherstats.com/v1/tokens/$NEW_TOKEN_ID \
  -H "Authorization: Bearer $US_TOKEN"

curl https://api.usherstats.com/v1/me \
  -H "Authorization: Bearer $NEW_TOKEN"

A token that makes tokens

An agent token with tokens:write can hand out narrower tokens, but nothing it does not hold itself:

curl https://api.usherstats.com/v1/tokens \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent", "scopes": ["tokens:write", "sites:read"], "expiresAt": "2027-12-31T00:00:00Z"}'

curl https://api.usherstats.com/v1/tokens \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "too wide", "scopes": ["sites:write"], "expiresAt": "2027-12-01T00:00:00Z"}'

curl https://api.usherstats.com/v1/tokens \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "reader", "scopes": ["sites:read"], "expiresAt": "2027-12-01T00:00:00Z"}'