Comma

API tokens & authentication

One token shape gates everything: the REST API, the MCP server, and the Claude Code plugin all authenticate with the same comma_sk_… Bearer token, checked by the same code path. Revoke a token once and the agent is out everywhere.

Minting a token

Settings → API tokens → New token in the app. The token value is shown once at creation — store it in a secret manager or environment variable, not in code.

Authorization: Bearer comma_sk_…

Tokens are stored hashed server-side; Comma cannot show you a token again after creation.

Scopes

Each token carries an explicit scope set. Grant the minimum the agent needs:

Scope Grants
reports:read List, search, and read report content, revisions, and diffs.
reports:write Create and edit reports; upload assets; request reviews.
comments:read Read comment threads and replies.
comments:write Post, reply to, and resolve comments.
routines Manage routines, skills, reviewers, and notifications.
connections Manage integrations and connectors.
sharing Change who can access a report.

New tokens default to reports:write, comments:write, and comments:read — enough for the publish-and-respond loop without letting the agent change sharing or touch automation.

A call with a missing scope fails with 403 Token missing scope: …. Note that scopes bound the token, not the user: the token can never do more than its owner can, and report-level access is always enforced on top.

Expiry and revocation

Tokens can carry an expiry date; expired tokens fail with 401. Revocation from Settings → API tokens is immediate and applies to the REST API and the MCP server in the same motion.

Rate limits

Per-token sliding window. The default is 60 requests/minute; paid plans can carry higher caps. When you hit the cap the API returns 429 with a Retry-After header — back off and retry rather than hammering.

Good practice for agent tokens

  • One token per agent. A Claude Code token, a CI token, a routine token — separate tokens mean separate blast radii and separate revocation.
  • Scope down. A CI pipeline that publishes coverage reports needs reports:write and nothing else.
  • Prefer env vars. The plugin installer writes ~/.config/comma/env (mode 0600); CI should use its secret store.

More patterns in Scoped tokens for AI agents →.