Scoped API keys: one key per agent, read-only, triage-only, or full

If you are running more than one agent against your issue tracker, you do not want them all holding the same key. The reporting bot that pastes a nightly summary should not be able to delete an issue. The CI job that files bugs should not be able to close them. And when one credential leaks, you want to kill that one and leave the rest running.

That is what scoped API keys are for: one key per agent, each granted exactly the access it needs, each revocable on its own. This is least privilege applied to a fleet of agents, and in Radial it is three scopes, one command, and no seat cost.

#The three scopes

Every Radial API key carries one of three scopes. The scope is the ceiling on what that key can do, enforced at the API boundary before any database call, so a read-only key can never reach a write path even if the agent tries.

• read is read-only: list, show, search, and export. It can see the work and nothing else. This is the scope for a dashboard, a nightly digest, an agent that reads context but never touches the tracker.
• triage is read plus the light triage mutations: assign, set status, set priority, and comment. It cannot create, close, delete, or import. This is the scope for a triage bot that sorts the incoming queue without ever originating or destroying an issue.
• write is everything: create, update, close, delete, import. This is the scope for the agent that actually does the work and writes the result back.

The mapping is deliberate. Triage is the interesting middle: it is the set of actions you want an automated sorter to take on the intake queue (route it, prioritize it, ask a question in a comment) minus the two verbs you almost never want to hand a bot unsupervised (creating issues from nothing and deleting them). If you have ever wanted to let an agent run your triage queue but felt nervous handing it a full-access key, this is the scope that closes that gap.

#Mint a key per agent, from the CLI

You do not need the dashboard to manage keys. The radial CLI mints, lists, and revokes them, which means you can bootstrap and rotate an entire agent fleet from a script:

# One key per agent, each scoped to exactly what it does
radial keys create "ci-bot"       --scope write    # files bugs from CI
radial keys create "triage-agent" --scope triage   # sorts the intake queue
radial keys create "standup-bot"  --scope read     # reads context, writes nothing

Each create returns the plaintext key exactly once, prefixed rk_ so it is recognizable in logs and secret scanners. Copy it into your secrets manager at that moment, because it is stored only as a SHA-256 hash on our side and is never shown again. If you lose it, you rotate it, you do not recover it.

List what you have, and revoke any single key without touching the others:

radial keys list                 # NAME  SCOPE  PREFIX  STATUS  ID
radial keys revoke <id>          # kill one credential, leave the rest running

Minting a key is a privileged action, gated to workspace owners and admins, so a member cannot quietly hand out access. And notably, key management is deliberately not exposed over MCP: an agent cannot mint itself a broader key. It gets the scope you gave it and that is the ceiling.

#One key, one agent identity, zero seats

Here is the part that changes how you think about a fleet. Each API key you mint provisions its own agent member in the workspace, and every agent member rides free. It never counts as a billed seat.

So the natural thing (one narrowly-scoped key per agent) is also the free thing. You are not choosing between good security hygiene and your bill. Spin up a read-only reporter, a triage-only sorter, and three full-access workers, each with its own revocable credential, and your price does not move. The humans on the workspace are the seats. The agents are clients of the API, the CLI, and the MCP server, and there is no per-agent charge and no AI credit meter anywhere in the product.

That is the Plain Software Pledge in practice: the day Radial ships a copilot, meters your usage, or charges you for AI you didn't ask for, your subscription is free. Scoped keys for a whole fleet cost the same as one key, which is to say they cost nothing beyond the flat $50 per user, per year, billed annually, for the people.

#When to reach for a key instead of OAuth

If you are connecting an interactive agent like Claude Code, you usually do not need a key at all. The MCP server uses OAuth, so you approve the connection in your browser and there is nothing to paste. Keys are for the non-interactive path: CI jobs, cron, headless agents, anything that runs without a human at the browser to click approve. That is where a scoped, revocable rk_ key is the right tool, and where per-agent scoping earns its keep.

#FAQ

#How should I properly handle a Radial API key?

Treat it like any secret: never commit it to version control, store it in a secrets manager or an environment variable, and give each key the narrowest scope that still lets its agent do its job. Radial helps by returning the plaintext only once, storing only a SHA-256 hash, prefixing every key rk_ for leak scanning, and letting you revoke any single key independently. Rotate a key by minting a new one and revoking the old one.

#What can someone do with my API key if it leaks?

Exactly what its scope allows, and nothing more. A leaked read key can list and export but cannot change anything. A triage key can assign, reprioritize, and comment but cannot create, close, or delete. Only a write key can do real damage. This is the whole argument for one narrowly-scoped key per agent: a leak is contained to that agent's ceiling, and you revoke that one key in a single command without disrupting the rest of the fleet.

#Why give each agent its own key instead of sharing one?

Two reasons: least privilege and clean revocation. Separate keys let you scope each agent to exactly what it needs (read-only for a reporter, triage-only for a sorter, full for a worker), and they let you kill one compromised or misbehaving credential without taking down every other agent that shares it. Because each key provisions its own free agent identity, there is no cost reason to share one.

#Does an extra API key cost extra?

No. Every API key provisions an agent member, and agent members never count as billed seats. You pay $50 per user, per year, for the humans on the workspace, and that number is locked at the rate you join. Mint as many scoped keys as your fleet needs.

#Can I manage keys without the dashboard?

Yes. The radial CLI does the full lifecycle: radial keys create <name> --scope read|triage|write, radial keys list, and radial keys revoke <id>. All three take --json, so you can script key rotation the same way you script everything else.

#The short version

Give each agent its own key, scope it to the minimum it needs, and revoke it on its own when you have to. Read-only, triage-only, or full, minted from the CLI in one command, each its own free agent identity. That is least privilege for an agent fleet without a seat cost or a credit meter.

See the full key lifecycle and the API surface on the developers page, or read how to wire Claude Code over MCP when the agent is interactive and OAuth is the shorter path.