# Scoped Tokens for AI Agents — one revoke, every surface

Canonical: https://commareports.com/agents/scoped-tokens-for-ai-agents

> An AI agent needs a credential. That credential needs to be scoped, revocable, rate-limited, and shared across every surface the agent touches. Comma's `comma_sk_…` token is that shape.

# Scoped tokens for AI agents

A working AI agent is a credential. Whatever the agent does — publish a
report, leave a comment, fire a routine, hit your warehouse — happens
under some token. The properties of that token determine the properties
of the agent's reliability and the blast radius when it goes wrong.

This page is about what good agent-token shape looks like, and how
Comma's `comma_sk_…` token implements it.

## Most agent incidents are credential incidents

Not "the model hallucinated." Not "the prompt regressed." The incidents
that actually take agent systems off the rails are credential incidents:

- The token was checked into a public repo.
- The laptop with the dotfile was stolen.
- The contractor left, but their token is still active.
- The token had every scope because nobody bothered to narrow it.
- One leaked token has access to four different APIs because the team
  reused it across surfaces.
- The agent was given a token, then somebody else used the same token
  manually, and now you can't tell whose action did what.

None of these are model problems. They are token-shape problems. The
fix is the same: make tokens narrow, make revocation easy, make rate
limits per-token, and don't share tokens across surfaces.

## Six properties of a good agent token

1. **Scoped.** The token grants specific actions on specific resources.
   Not "everything this account can do."
2. **Revocable, immediately.** One click in a settings UI; the token is
   dead within seconds, everywhere it was honored.
3. **Rate-limited per token.** A misbehaving agent under one token
   doesn't drag down the rest of the account.
4. **Auditable.** Every call the token made is recorded, with the token
   identifier attached, so you can answer "who did this" after the fact.
5. **Single-surface.** The token gates one auth surface, not three. When
   you revoke it, you're not chasing it across four product areas.
6. **Cheap to rotate.** New tokens take seconds to create. Rotation is
   not a Friday-afternoon project.

A credential with all six is the foundation of an agent system that
fails safely. A credential with three of these is a future incident.

## How Comma's `comma_sk_…` token implements this

### Scoped

When you create a `comma_sk_…` token in **Settings → API tokens**, you
pick its scopes:

- `reports:read` — can read existing reports
- `reports:write` — can create and update reports
- `comments:read` — can list comments
- `comments:write` — can add, reply to, and resolve comments
- `routines:write` — can create and update routines

Most agents need only the scopes they actually use. An agent that
publishes reports but doesn't manage routines doesn't get `routines:write`.

### Revocable in one motion

From the same screen, one click revokes a token. Revocation propagates
within seconds and applies to **every surface the token touches** — the
REST API at `/api/v1/*`, the MCP server at `/api/mcp`, and any routine
the token created (the routine pauses).

There is no "but it also has a Slack webhook" to chase. The Comma
credential is the one credential.

### Rate-limited per token

Every token has its own rate limit. The rate limit is part of the token
record, visible alongside it. A token with a tighter limit can be
allocated to a riskier agent (a new experimental skill) without putting
the account-wide ceiling at risk.

### Auditable

Every call records the token identifier. Compliance digests, audit
exports, and the per-routine run history all reference the originating
token. When a stakeholder asks "which agent posted this," the answer is
in the audit trail.

### Single-surface

The same `comma_sk_…` token is the auth for:

- The REST API (`/api/v1/*`)
- The MCP server (`/api/mcp`)
- Routines executed under it

That is not a "we accept this token in multiple places" coincidence. It
is the same auth surface presented in multiple shapes. Revoking the
token revokes every shape simultaneously.

### Cheap to rotate

Creating a new token takes one form and one click. The form prompts
for a name and scopes. There is no approval workflow for routine
rotation. Rotate as often as you like.

## Practical token policy for agent systems

Tested patterns from teams that have been doing this for a while:

### One token per agent

The clearest model. Every running agent (Claude Code on a developer's
laptop, a scheduled Claude skill in production, a Cursor agent at the
office) gets its own token with its own scopes and its own rate limit.
When the agent is retired or the developer leaves, revoke the specific
token; everything else keeps running.

### One token per workspace `.cursor/mcp.json` or `.claude/mcp.json`

If you'd rather group by editor / workspace than per-agent, the
workspace-config-file approach works. Treat the per-project token like
the project's other secrets — not in a public repo, rotated when team
membership changes.

### Read-only tokens for read-only agents

If an agent only needs to _read_ reports — a watcher that checks for
new comments and emails you a summary — give it `reports:read` and
`comments:read` only. The write surfaces stay protected.

### Separate human and agent tokens

Don't use the same token for "I'm hitting the REST API by hand" and
"my agent uses it." When you need to revoke one, you don't want to
break the other.

### Tight per-token rate limits during ramp-up

New agent in production? Start its token with a tighter rate limit and
loosen as the agent proves itself. The cost of a too-tight limit is
"agent works slightly slower." The cost of a too-loose limit is the
agent burns through your budget in an hour.

## What the token does _not_ gate

Worth being explicit:

- **No general AWS access.** A Comma token doesn't reach into your AWS
  account. (Bring-your-own Bedrock keys, available on any plan, plug in your
  _Bedrock_ credentials separately; those are your AWS responsibility.)
- **No Slack or email side-effects.** Comma posts to a Comma report. The
  token doesn't grant the agent a path to Slack or email.
- **No code execution.** The token authorizes data operations on
  Comma's surface — reports, comments, routines. It does not turn Comma
  into a code-execution sandbox for the agent.

This is the _narrow_ part of "narrow scope." The token doesn't pretend
to be a key to your whole stack.

## Try it

Generate a `comma_sk_…` token in **Settings → API tokens**, scope it to
what your agent actually needs, and revoke it any time. Free tier
includes token creation and full revocation.

**[Create a token →](https://commareports.com/settings/tokens)**

### Related

- [Where should my AI agent post its work?](/agents/where-should-my-agent-post)
- [Give an agent feedback](/agents/give-an-agent-feedback)
- [Let an agent respond to comments](/agents/let-an-agent-respond-to-comments)
- [Comma MCP server overview](/mcp)