An API token (key) lets a script, another system, or an AI agent use SAQ over HTTP or MCP. There are two kinds. A personal token acts on behalf of the person who created it and can never do more than that person may. An agent account is a workspace user of its own that exists only as a key: it is the actor on everything it does. This page explains both, and where owners and admins see and revoke every key in the workspace.
Before you start
- Personal tokens: you need a full login (password, passkey, or single sign-on), not a magic-link session, and you confirm your identity when creating one. Owners and admins must have two-factor authentication. Regular client users cannot create tokens; elevated client users can, for the projects they are elevated on.
- Agent accounts and the workspace registry: you need the Owner or Admin role.
- Keys cannot be created with another key. Minting always happens in the browser.
Scopes
Every key carries one or more scopes. Read is always included.
| Scope | Allows |
|---|---|
| Read | Tickets, boards, My work, time, documents, and the workflow that the person or agent can already see. |
| Write | Create and update tickets, comment with attachments, move state and project, link tickets (dependencies, parent, GitHub), and log time. |
| Triage (shared Inbox) | Read and route the shared Inbox. Workspace users only; client users cannot grant it. |
Some operations never work with a key, whatever its scopes: archiving and deleting tickets, viewer grants, period close, billing runs and voids, redaction, client management, member and token management, workspace settings, and the account pages. See Authentication for integrations.
Personal tokens
- Open Account → API tokens.
- Fill in the form and select Create token; confirm your identity. The secret is shown once: copy it now.
| Field | Meaning |
|---|---|
| Workspace | The workspace the key is bound to. One key, one workspace. |
| Name | A label for the list, up to 80 characters. |
| Scopes | Read, Write, Triage, as above. |
| Projects | Leave empty for every project you belong to. A named list restricts the key to those projects, and a project-scoped key never sees the Inbox. Elevated client tokens must name at least one project. |
| Allowed addresses | Optional IPv4 address or prefix (CIDR). Empty means any address. |
| Expires | Never, or After {n} days. |
Your tokens are listed with Prefix, Last used, and Expires; Revoke stops one immediately. Last used is updated at most once a minute.
A personal token is limited by the person's current permissions on every request. Losing a project membership takes that project out of the key at once. Tickets and comments created through a key are marked with source api or mcp, and audit entries are attributed to the key's owner and marked as made on their behalf.
Agent accounts
An agent account is a workspace user for automation, created under Settings → People → Members, section Agent accounts. Its address is handle@workspace, for example claude@acme: not a mailbox, and never in conflict with a person. Agents cannot log in with a password or a magic link; the key is their only credential. They are always members, automatically belong to every project (including projects created later), and each has exactly one live key.
- Enter a Name and a Handle (letters, digits, dots, dashes, underscores).
- Choose the Scopes and select Create agent; confirm your identity. Copy the key now.
The table lists Address and key Prefix. Rotate revokes the current key and issues a new one with the same name, scopes, restrictions, and expiry, shown once. Revoke stops the key without removing the agent; a new key can be issued later. Agents also appear in the members table marked "(agent)".
The workspace registry
Settings → Channels → API tokens lists every key bound to the workspace, personal and agent: Name, Owner, Kind, Prefix, Scopes, Projects, Allowed addresses, Created, Last used, Expires, and Status. Owners and admins can Revoke any key here; it stops working immediately and its owner can create a new one. Revoked keys stay listed for 30 days. Keys are not created on this page.
When keys are revoked automatically
- Promoting a person to Owner or Admin, or demoting them to Member, revokes their personal tokens. They re-mint under the new role.
- Forcing single sign-on on a domain revokes the personal tokens of everyone on that domain; minting a new one then requires a session that came through single sign-on. See Authentication settings overview.
- Removing a person from the workspace, or a SCIM deactivation, revokes their keys.
- An expired key stops working at its expiry.
Rate limits
Each key may make 120 requests per minute, and all keys in a workspace share the plan's budget (300, 1 200, or 3 000 requests per minute depending on the plan). Over the limit, requests are refused with "This token has reached its rate limit. Wait a minute and try again."
Connect an AI tool
Settings → Channels → MCP setup shows ready-made configuration for Claude Code and Cursor. Replace saq_YOUR_TOKEN with a key you minted. Cookie sessions are ignored on the MCP path; only keys work there. See MCP and Connect an AI agent.
Common problems
"Regular client users cannot create API tokens." Only elevated client users (members of a project) can, and they must name a project.
"Elevated client tokens must name at least one project." Pick the projects under Projects.
"Confirm your identity to continue." Minting needs a recent full login. Use your password, a passkey, or sign in again through single sign-on.
A key that worked yesterday is refused today. Check the registry for Revoked: a role change, forced SSO, or removal revokes keys. Check Expires too.