Skip to content
Toado Docs

API tokens

API tokens are how anything outside the web app authenticates to Toado: the MCP server, direct REST calls, custom integrations, CI scripts.

This page covers tokens from an end-user perspective. For the AI agent perspective with the full scope matrix, see Tokens & scopes (Claude Code).

Creating a token

Settings › API tokens › New token.

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.

Pick a label, choose scopes, optionally restrict to specific companies or projects, click Create. The token string is shown once. Copy it immediately; you cannot retrieve it later.

What scopes do

Four scopes:

  • read: read everything (companies, projects, columns, tickets, comments, members, capture assets).
  • comments: post comments. Includes read.
  • tickets:write: create, edit, archive, restore, move tickets, plus record the worked-on git branch. Includes read and comments.
  • tickets:assign: assign and unassign users on tickets. Includes read.

Pick the narrowest set that fits the use case.

Use caseRecommended scopes
Claude Code triage agentread, comments, tickets:write, tickets:assign
Read-only reporting / dashboardsread
Slack bot that posts commentsread, comments
External system that updates ticket statusread, comments, tickets:write
Per-project agent with no assignment powerread, comments, tickets:write

Restricting a token

When creating, you can restrict the token to:

  • One or more companies.
  • One or more projects within those companies.

A restricted token sees only the chosen scope. Listing operations return only matching rows; writes against other rows return forbidden.

Use restrictions when:

  • The token is for a skill that should only touch one project.
  • You are running Toado as a managed service for clients and want one token per client.
  • You want to embed a token in CI and minimize blast radius.

Where to put the token

ContextWhere
Claude Code via MCPTOADO_API_TOKEN env var, set in your MCP config. See Installation.
Direct RESTAuthorization: Bearer tok_... header.
Local dev.env file, ignored by git.
CIYour CI’s secrets manager (GitHub Actions secrets, etc.).
Production appYour platform’s secret manager (Vercel env vars, etc.).

Rotating

Two safe patterns:

  • Side-by-side: create the new token, update your config, restart, then revoke the old.
  • Cut-over: revoke the old, create the new, update config. Faster but every in-flight call from the old token is rejected immediately.

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

Visibility into what tokens did

Every write operation records the token id, the token label, and the token owner on the resulting row. In the UI:

  • Comments show: Jason (claude-code on macbook) · via MCP.
  • Ticket edit history (when ticket history is shipped) will show the same.

This makes it easy to audit what each token has been doing.

Limits

  • No hard cap on number of tokens per user (within reason).
  • Per-token rate limits: 600 reads / minute, 60 writes / minute (configurable per company).
  • Revoked tokens count against no quota.

Where to next