Permissions API
CRUD operations for agent permission layers — define what each agent is and isn't allowed to do.
The Permissions API lets you define and manage the permission layer for every agent in your system. Permissions control which tools an agent may call, which data paths it may read or write, which network destinations it may reach, and how much compute it may consume per run. The Gate API enforces these permissions at runtime.
GET /api/permissions/{agent_id}
/api/permissions/{agent_id}
Returns the current permission configuration for the specified agent.
Response
{
"agent_id": "invoice-processor",
"version": "1.2",
"tools": {
"allow": ["read_invoice", "write_invoice_status", "send_confirmation"],
"block": ["shell_execute", "delete_record"]
},
"data": {
"read": ["invoices/*", "customers/*/email"],
"write": ["invoices/*/status"],
"deny": ["customers/*/payment_method"]
},
"network": {
"allow": ["api.company.com"],
"block_outbound": true
},
"compute": {
"max_tokens_per_run": 10000,
"max_tool_calls_per_run": 20
},
"updated_at": "2026-04-05T10:00:00Z"
}| Field | Type | Description |
|---|---|---|
tools.allow | string[] | Explicitly permitted tool names |
tools.block | string[] | Always-blocked tools, regardless of other rules |
data.read | string[] | Glob patterns for readable data paths |
data.write | string[] | Glob patterns for writable data paths |
data.deny | string[] | Explicitly blocked data paths, highest precedence |
network.allow | string[] | Whitelisted outbound hostnames |
network.block_outbound | boolean | Block all outbound traffic not in allow |
compute.max_tokens_per_run | integer | Hard limit on tokens consumed per run |
compute.max_tool_calls_per_run | integer | Hard limit on tool calls per run |
POST /api/permissions/{agent_id}
/api/permissions/{agent_id}
Create a new permission configuration for an agent that has not yet been registered. Returns 409 Conflict if permissions already exist for the given agent_id — use PUT to replace or PATCH to update.
The request body accepts the same schema as the response from GET /api/permissions/{agent_id}, omitting version and updated_at (both are set by the server).
PUT /api/permissions/{agent_id}
/api/permissions/{agent_id}
Replace the entire permission configuration for an agent. Any fields not included in the request body are reset to their default values. If no permissions exist for this agent yet, a new record is created (upsert behavior).
The prior version is retained in the permissions history and remains accessible via the audit log.
PATCH /api/permissions/{agent_id}
/api/permissions/{agent_id}
Partially update an agent's permissions without replacing the entire object. Use add_allow / remove_allow and equivalent keys to surgically modify allow and block lists.
Request body
{
"tools": {
"add_allow": ["read_customer_record"],
"remove_allow": ["write_invoice_status"]
}
}| Key | Effect |
|---|---|
tools.add_allow | Append items to tools.allow |
tools.remove_allow | Remove items from tools.allow |
tools.add_block | Append items to tools.block |
tools.remove_block | Remove items from tools.block |
data.add_read | Append patterns to data.read |
data.add_deny | Append patterns to data.deny |
DELETE /api/permissions/{agent_id}
/api/permissions/{agent_id}
Remove all permissions for an agent. Once deleted, any gate evaluation for this agent will return block with the reason "no_policy_found" until a new permission set is created.
Use with caution in production environments. The deletion is logged in the audit history and can be reviewed, but cannot be automatically undone.
Returns 204 No Content on success.