Access Tokens & Devices

An access token (aso_agt_…) lets something other than a person read your organisation's usage and cost data through the Usage Query API: a cron script, a Grafana panel, an MCP client, or a hardware device such as a desk spend meter. Each token has its own name, its own scopes, and its own audit trail, so you never have to share a person's login or embed a proxy key somewhere it does not belong.

Access tokens are read-only. They cannot change settings, manage keys, or make LLM calls.

Terminology

Internally, and in the Management API, each token belongs to an agent: a non-human identity with an agent_id. You will see that word in the audit log, in API paths such as /agents/{id}/rotate, and in the token prefix aso_agt_. In the portal and these docs we simply call them access tokens.

Access tokens are not proxy API keys

	Proxy API key (aso_k_…)	Access token (aso_agt_…)
Purpose	Route LLM traffic through the proxy	Read usage and cost data
Sent to	proxy.aispendops.com with your LLM calls	api.aispendops.com
Can spend money	Yes, it fronts provider traffic	No, read-only
Typical holder	Your application	A dashboard, a script, an MCP client, a desk meter
Managed in	Settings → Proxy API Keys	Settings → Access Tokens

Keep them separate: a leaked access token exposes aggregate numbers, never the ability to make provider calls.

Creating a token

1. Go to Settings → Access Tokens (administrator role required to create; all roles can view).
2. Choose Create token, name it after where it will live (for example "Grafana spend panel"), tick the scopes it needs, and optionally set an expiry.
3. Copy the token from the dialog. It is shown exactly once and stored only as a hash: if you lose it, rotate to get a new one.

Use it as a bearer token:

curl "https://api.aispendops.com/v1/usage?metric=cost_usd&window=month_to_date" \
  -H "Authorization: Bearer aso_agt_..."

Scopes

Tokens hold only the scopes you grant. Start with the narrowest set that does the job; you can widen or narrow a token later without re-issuing it.

Scope	Grants	Needed for
read:usage	Cost, request, and token aggregates	Everything: totals, per-provider, per-model, per-dimension, daily trend
read:keys	API key names	dimension=api_key breakdowns, since per-key spend reveals how keys are used
read:budgets	Reserved: budget data is not yet available to tokens	Nothing yet

Every token can always read its own profile and send heartbeats. Narrowing a token's scopes takes effect within a minute.

The Type column on the Access Tokens page tells you how a token was created and what it is for: hand-created tokens show as API token (or API token (usage only) when limited to read:usage), and paired hardware shows as Spend meter.

Pairing a device

Hardware devices pair with a short code instead of a typed token:

1. Power the device on: it shows a six-character code (for example M3X-7KQ).
2. In Settings → Access Tokens, choose Pair a device and enter the code.
3. Confirm the details shown: device type, where the request came from, and when.
4. The device collects its token automatically within a few seconds.

The token is delivered directly to the device, exactly once, and is never shown in the portal.

Never enter a code that was sent to you

Codes belong on a screen you are physically looking at. If someone messages you a pairing code, entering it would connect their device to your organisation's data.

Managing tokens

• Last used: any authenticated call updates the token's last-used time and IP (refreshed at most every 5 minutes). This is the activity signal for scripts and dashboards, which typically never heartbeat, and it is how you spot a token being used somewhere you did not expect.
• Last seen: devices that report a heartbeat (meters, TV dashboards) additionally get a live/idle/offline indicator, the heartbeat IP, and the reported client version.
• Expiry: an optional expiry set at creation. Expired tokens are rejected with 401; rotate to issue a fresh one.
• Rotate: issues a new token and invalidates the old one immediately on the issuing instance, and within about 60 seconds everywhere. Rotating a paired device's token means the device must be paired again.
• Revoke: permanently disables the token. Same propagation window as rotate.
• Audit: creation, pairing, rotation, revocation, and scope changes all appear in Settings → Audit Log.

Security model

• Tokens are 256-bit secrets stored only as peppered hashes; plaintext exists once, in the creation dialog or on the device.
• Tokens are scoped to a single organisation and go through the same row-level isolation as every portal user.
• All token endpoints are rate limited; a runaway script gets 429 with a Retry-After header, not a bigger bill.

Next steps

• Usage Query API reference: every metric, window, and dimension a token can query.