Permission Requests

When an agent needs access to tools outside its current allow list, it can submit a permission request. Workspace members review and approve or reject requests, creating a controlled escalation path for tool access.

Viewing pending requests

bash

# List pending permission requests
curl http://localhost:3000/permission-requests \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Response
{
  "requests": [
    {
      "id": "pr_abc123",
      "workspace_id": "ws_abc123",
      "agent_id": "code-agent",
      "uid": "uid_alice",
      "requested_tools": ["shell_execute", "file_write"],
      "reason": "Need shell access to run deployment scripts",
      "status": "pending",
      "reviewed_by": null,
      "created_at": "2026-03-07T12:00:00.000Z"
    }
  ]
}

Approving or rejecting

The reviewer's user ID is recorded on the request. Only pending requests can be reviewed — already-approved or rejected requests return 404.

bash

# Approve a permission request
curl -X POST http://localhost:3000/permission-requests/pr_abc123/approve \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Reject a permission request
curl -X POST http://localhost:3000/permission-requests/pr_abc123/reject \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Endpoint reference

Method	Endpoint	Description
`GET`	`/permission-requests`	List pending requests for workspace
`POST`	`/permission-requests/:id/approve`	Approve request
`POST`	`/permission-requests/:id/reject`	Reject request