# API tokens & authentication · Comma Docs

Canonical: https://commareports.com/docs/api-tokens

> How Comma API tokens work: the comma_sk_ format, granular scopes, default scopes, expiry, instant revocation, and per-token rate limits.

# 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 →](/agents/scoped-tokens-for-ai-agents).