API token

An API token is a bearer key that lets a program act in a workspace, either on behalf of a person (delegated) or as an agent account, limited by scopes, projects, addresses, and expiry.

Written for
admin, integration-developer
Roles
owner, admin, member, elevated-client-user, agent
Requires
Feature
tokens

An API token (key) is the credential a script, an integration, or an AI assistant presents to SAQ as Authorization: Bearer saq_…. It never carries more rights than the person or agent it belongs to. There are two kinds. A delegated token is minted by a person under Account → API tokens and acts on their behalf; what it does is attributed to them and recorded as done through the key. An agent key belongs to an agent account, a token-only workspace user.

How it relates to other concepts

  • Scopes: Read (always included), Write, and Triage (the shared Inbox). Client users can never grant Triage.
  • A token may be limited to a list of projects. Left empty, it covers every project the person belongs to. A project-limited token never sees the Inbox. An elevated client user's token must name at least one project; regular client users cannot mint tokens at all.
  • The organization's plan sets a request budget shared by every key in the workspace, on top of 120 requests per minute per key.

Rules

  • The secret is shown once, at creation. Afterwards only its prefix is displayed.
  • Minting needs a browser session with a full login and a recent re-authentication; Owners and Admins need two-factor authentication. A token can never mint, list, or revoke tokens.
  • Optional restrictions: allowed addresses (IPv4 address or prefix) and an expiry (never, or after a number of days).
  • Tokens work only on the workspace API and MCP. They cannot manage account settings, workspace configuration, authentication, clients, billing, or tokens, and they cannot close periods, run billing, archive or delete tickets, add viewers, or redact.
  • Revocation happens on request, when the person is removed, when they move between Member and Owner/Admin, and when single sign-on is forced for their domain. Owners and Admins see every key in Settings → API tokens and may revoke any; revoked keys stay listed for 30 days.
  • Tickets and comments created through a key record the source api (HTTP) or mcp.

Example

A consultant mints a Write token limited to retail-shop for a script that files deployment tickets. When she is promoted to Admin, the token is revoked and she mints a new one after setting up two-factor authentication.

  • API tokens and agent accounts The two kinds of API keys in SAQ, personal tokens and agent accounts, their scopes, restrictions, and expiry, and how owners and admins oversee and revoke them.
  • Authenticate with API tokens How to obtain a personal token or an agent account key, send it as a bearer token, and what scopes, project limits, address restrictions, expiry, and revocation do.
  • Connect an MCP client The MCP endpoint, how Claude Code and Cursor are configured, every tool with its arguments and result, error shapes, rate limits, and the context pack.
  • API tokens and agents Mint, list, and revoke API tokens, manage agent accounts, and fetch MCP setup snippets through the SAQ REST API; all of these are browser-session only.
  • Agent account An agent account is a token-only workspace user with the address handle@workspace, always a Member and on every project, holding exactly one live API key.