Tokens & scopes

Every MCP call (and every direct REST call) carries a per-user API token. Tokens have scopes, can be restricted to specific companies and projects, and can be revoked instantly.

Token shape

Tokens are created in the web app under Settings › API tokens. Pick a label, choose scopes, and optionally restrict to specific companies or projects. The token string is shown once at creation time and cannot be retrieved later, so save it immediately.

Label claude-code on my-laptop Human-readable name. Shows up on every comment and edit the token makes.

Scopes read comments tickets:write tickets:assign Granular. Read-only audit tokens want just read. Full-power agents want all four.

Company filter All companies (no filter) Restrict to one company id to scope down a token.

Project filter All projects in those companies Restrict further to specific projects.

Output looks like tok_01HXYZ123ABCD.... Treat it like a password. Revoke at any time from the same settings page; revocation is effective immediately.

Scope matrix

Scope	What it grants	What it does not grant
read	Read companies, projects, columns, tickets, comments, members, capture assets, annotations, search.	No writes of any kind.
comments	Post comments on tickets. Includes read.	No ticket edits, no assignments, no archiving.
tickets:write	Create, update, archive, restore, move tickets, plus record the worked-on git branch. Includes read and comments.	No assignment changes.
tickets:assign	Assign and unassign users on tickets, individually or in bulk. Includes read.	No ticket edits or comments.

A common production setup is to give your Claude Code agent all four scopes (it does the most). Audit-only or read-only tokens for dashboards and exports get just read.

Restricting a token

When you create a token you can pin it to:

• One company (or several, by creating one token per company).
• Specific projects within those companies.

A token restricted to company co_abc123 and project proj_xyz789 will see only that project. List operations return only matching rows; writes against other rows return forbidden.

This is the right pattern for:

• Skills that should only touch one project.
• Tokens you embed in CI or agents you do not fully trust.
• Per-customer tokens if you are running Toado as a managed service for clients.

Per-skill tokens

If you run multiple skills (one for triage, one for verification, one for screenshot regression sweeps), give each its own token with the narrowest scope it needs. The token label appears on every comment, so per-skill tokens make audit trails self-explanatory.

Authentication header

For direct REST calls (not via MCP), pass the token as a Bearer:

curl https://api.toado.dev/api/v1/me \
  -H "Authorization: Bearer tok_01HXYZ..."

The MCP server handles this for you when you set TOADO_API_TOKEN in the env.

Rotating tokens

Two safe patterns:

Side-by-side rotation (recommended). Create a new token with the same scopes, update your config to use it, restart your client, then delete the old token. Zero downtime.

Cut-over rotation. Delete the old token, create a new one, update your config. Fastest, but every in-flight call from the old token is rejected immediately. Fine for one-off agent contexts.

Revocation is effective immediately. The next request with a revoked token returns 401 unauthorized.

Rate limits

Limit	Default	Configurable per company
Reads	600 / min / token	Yes
Writes	60 / min / token	Yes

429 responses include a retry_after header (seconds). The MCP server’s bulk tools (bulk_move_tickets, bulk_assign_tickets) call sequentially to stay inside the write budget, capping at 50 tickets per call.

Storage and exposure

• Tokens are hashed at rest. The plaintext is shown once at creation; we cannot recover it.
• Treat tokens like passwords: do not commit to version control, do not paste into shared chat threads.
• For local development, use a .env file ignored by git.
• For production, store in your platform’s secret manager (Vercel env vars, GitHub Actions secrets, etc.).

Comparing identities

Every write operation records the token’s owner and the token label. In the UI, comments and edits from MCP clients show:

Jason (claude-code on macbook) · via MCP · just now

That makes it easy to tell which agent or human did what, even when one user has several tokens.

Where to next

• Tools reference for the full surface and what each tool needs.
• API tokens (user view) for the same topic framed for end users.
• Security for the broader trust model.