What does 'scoped' mean for an AI agent's token?

Scoped means the token is limited in what it can do: which reports it can read or write, whether it can create routines, whether it can manage comments. You set the scopes when you create the token. Most agent incidents are credential incidents — narrow scopes contain the damage.

Why does revocation matter for agents?

Because agents leak tokens. Laptops get lost, repos get pushed public, employees leave with their dotfiles. The blast radius of a leaked token is the surface area it covers. A token that gates four different APIs needs four revocations; a token that gates one needs one. Comma's `comma_sk_…` token gates the REST API, the MCP server, and any routines it created — revoke once.

Is rate-limiting per-token or per-account?

Per token. A misbehaving agent under one token can't drag down the rest of the account. This also means you can give a riskier agent a tighter per-token rate limit.

Should I use a different token per agent?

Yes. The general practice: one token per agent, one token per workspace, or one token per project. When something goes wrong (or an employee leaves), you revoke the specific token and the rest of your agent fleet keeps running.

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

Scoped. The token grants specific actions on specific resources. Not "everything this account can do."
Revocable, immediately. One click in a settings UI; the token is dead within seconds, everywhere it was honored.
Rate-limited per token. A misbehaving agent under one token doesn't drag down the rest of the account.
Auditable. Every call the token made is recorded, with the token identifier attached, so you can answer "who did this" after the fact.
Single-surface. The token gates one auth surface, not three. When you revoke it, you're not chasing it across four product areas.
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. (BYOK on the Team plan plugs in your Bedrock keys separately; those credentials 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 →