Configure an agent’s permissions

The agent’s detail page at /agents/:id is where you change what it’s allowed to do.

Open the agent

Agents → Agents in the sidebar → click any agent card. The detail page has:

Agent identity (name, ID, SPIFFE ID if it has one, status, rate limit)
Suspend / Re-activate buttons and the key-rotation flow (Rotate & get command / Rotate & show config)
The agent’s grants — one row per platform it can reach, listing the scopes it holds
Danger Zone at the bottom, for deletion

Add a permission

Click + Grant access. The Grant platform access form asks you to:

Pick a platform. If it has more than one connection, choose All connections (platform-wide) or Specific connections.
Select scopes (or Select all).
Decide whether to tick Require human approval before each action.
Choose when Access expires (or leave it so access stays until you revoke it).

Click Save access.

Some rules to keep in mind:

The platform must already be connected under Platforms → Connections. If it’s not there, connect it first.
Scopes come from the platform’s catalog — for example github:repo.read or github:contents.write. See Scopes & permissions for the underlying model.
The approval setting belongs to the whole grant row (the platform), not to individual scopes. When it’s on, every call through that grant queues for approval — reads included. For per-scope approval, use Ask first in the member’s policy.

Bounded by the owner’s policy

An agent’s grantable scopes are bounded by the policy assigned to its owner. If the owner’s policy doesn’t allow a scope, it appears greyed out in the picker (“Not allowed by your assigned policy”) — you can see it but you can’t grant it. If an existing grant covers a platform the policy doesn’t allow, its row shows a Blocked by policy badge; admins get an Allow Platform in policy button right there. Otherwise, lift the bound by editing the owner’s policy or assigning a different one on the Team page.

Org guardrails sit even higher: a scope denied by a guardrail is refused for everyone, regardless of policy or grant.

Revoke a permission

Use Edit scopes on a grant row to drop individual scopes, or Remove to take the platform away from the agent entirely (you’ll be asked to confirm). The agent’s next call using a removed scope is refused — there is no propagation delay.

Suspend on a grant row pauses that one platform for the agent without deleting the grant; Unsuspend restores it.

Flip the approval toggle

Each grant row has an approval toggle, so you can change it without revoking and re-granting. Useful when you’ve watched an agent operate safely for a while and want to drop the friction on a platform.

Reverse direction (turning approval back on) is just as safe — the next call queues instead of running. Members see the toggle locked; only an admin can change it.

What gets audited

Grant changes aren’t written to the audit log as their own rows. What you’ll see in Audit Log → Actions is the effect on the agent’s calls — allowed, denied (for example scope_not_granted), or pending approval.

When in doubt

The cheapest configuration is grant read scopes freely, and put writes and anything destructive behind approval — turn on the policy’s Ask me first before anything destructive preset, and use Ask first for writes. You can always loosen it.