Skip to main content

​
The credential

An agent access token is a scoped API key, distinct from the singular full-access personal access token your dashboard integrations use: Mint and manage agent keys in Settings → API & Agents (see the in-app Help Center for the UI walkthrough). Each key is owned by the admin who created it and acts as that user — role permissions still apply on top of scopes.

​
How a call authenticates

  • Token — sent as Authorization: Bearer <key> (the MCP server relays it to the API as the api_access_token header). Direct REST callers send api_access_token: <key> themselves.
  • Account — fixed by the X-Sapot-Account-Id header (MCP) or the /api/v1/accounts/:id/… path (REST). A key is bound to the one account it was minted in, even if its owner belongs to several — a mismatched account id is refused.

​
Capability scopes

​
Default-deny model

Authorization is an allowlist: each endpoint + action is paired with the scope that unlocks it. The rule is default-deny:
  • An endpoint not in the allowlist is refused for agent tokens — even with *. (* grants every mapped scope, not a bypass.)
  • An endpoint in the allowlist but whose scope you weren’t granted is refused with missing the required scope: <scope>.
Both refusals are expected behavior, not bugs. Name the missing scope and stop — don’t blind-retry. If the capability should be available, add the scope to a new key (you can’t widen a key in place).

​
Account binding + role checks

Two layers apply, in order:
  1. Scope allowlist — is this endpoint reachable with this key’s scopes, in this account?
  2. Role — the owning user’s role still gates the action. A key can’t do what its owner couldn’t do in the dashboard (e.g. admin-only actions need an admin owner).
So * is “everything this user may do, through the mapped surface” — never more than the human behind the key.

​
Security guidance

  • Least privilege — grant only the scopes an integration needs; one key per integration.
  • Short expiries — set an expiry; rotate by revoking and minting a new key.
  • Revoke on suspicion — instant, and affects only that key, never your login or other keys.
  • The plaintext token is shown once on creation — store it like a password.