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. (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 →
Related