← back to docs

Agent authorization

IAM for agents.

The boundary manifest is what a developer declared a run may do. Authorization is what the org allows an agent to do right now: scoped capabilities, granted just-in-time, revocable in real time. As MCP and tool use spread, “what is this agent allowed to do, and can I revoke it now” is the question, and the manifest plus the gateway already answer it.

Capabilities

An agent is identified by its source.app_id (the kebab-case id on its receipts, e.g. claims-orchestrator). A capability is one of two things the agent does, namespaced:

  • tool:<name>: a tool / function call (matched against the tool on a tool_call event).
  • scope:<name>: a data scope the agent touches (matched against the data_scopes on a step).
  • Wildcards: tool:*, scope:*, and * for all.

Grant, revoke, expire

  • Grant (effect allow): authorize a capability. Required in strict mode. Give it an expiry for just-in-time access that lapses on its own.
  • Revoke (effect deny): block a capability immediately, in any mode. The kill switch. It takes effect on the agent's very next gateway or ingest call, because enforcement loads grants per event. No redeploy, no cache to clear.

Two modes

  • monitor (default): the agent runs as before, and any revocation you add blocks that capability in real time. Nothing breaks until you revoke something.
  • strict: default-deny least privilege. The agent may use only capabilities it has an active grant for; everything else is blocked. Opt in per agent.

Enforced before execution

The agent_authorization policy runs on both the ingest path (attested after) and the gateway check (blocked before execution). For gateway-routed traffic, a revoked capability is a guarantee: the call never reaches the vendor. Either way the blocked attempt is a signed receipt in the Audit Vault, and every grant, revoke, and mode change is a signed operational receipt.

API

# Revoke a tool from an agent, right now (the kill switch).
curl -X POST https://prova.cobound.dev/api/v1/agents/claims-orchestrator/grants \
  -H "Authorization: Bearer $PROVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "capability": "tool:send_email", "effect": "deny", "reason": "incident-1234" }'

# Grant a scope just-in-time (lapses in 1 hour).
curl -X POST https://prova.cobound.dev/api/v1/agents/claims-orchestrator/grants \
  -H "Authorization: Bearer $PROVA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "capability": "scope:claims_db", "effect": "allow", "expires_at": "2026-05-26T13:00:00Z" }'

# Flip the agent to least-privilege (default-deny).
curl -X PATCH https://prova.cobound.dev/api/v1/agents/claims-orchestrator \
  -H "Authorization: Bearer $PROVA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "mode": "strict" }'

Managing grants needs an API key (or member) with agent.authorize. Manage it all in the dashboard.