# Permissions

Every permission a role can carry, grouped by area, with who can hold it and the endpoints that require it.

## Organization

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `organization.delete` (dangerous) | Schedule the organization for deletion | human, api_key |  |
| `organization.read` | Read organization settings and policy | human, api_key, organization_api_key |  |
| `organization.settings.write` | Change organization settings and policy | human, api_key |  |

## Membership

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `membership.invite` | Invite people and manage pending invitations | human, api_key | GET /api/v1/invitations, POST /api/v1/invitations, POST /api/v1/invitations/{id}/resend, DELETE /api/v1/invitations/{id} |
| `membership.read` | List members and pending invitations | human, api_key, organization_api_key | GET /api/v1/members |
| `membership.write` | Suspend, reactivate, and remove members | human, api_key | PATCH /api/v1/members/{id}, DELETE /api/v1/members/{id} |

## Team

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `team.escalation.activate` | Activate, roll back, and deactivate team escalation policies | human, api_key, organization_api_key | POST /api/v1/teams/{id}/escalation-policy/revisions/{revision}/activate, DELETE /api/v1/teams/{id}/escalation-policy/active |
| `team.escalation.write` | Create team escalation policy revisions | human, api_key, organization_api_key | POST /api/v1/teams/{id}/escalation-policy/revisions |
| `team.member.write` | Change who is on a team | human, api_key | PUT /api/v1/teams/{id}/members |
| `team.read` | List teams and their rosters | human, api_key, organization_api_key | GET /api/v1/teams, GET /api/v1/teams/{id}, GET /api/v1/teams/{id}/escalation-policy, GET /api/v1/teams/{id}/escalation-policy/revisions, GET /api/v1/teams/{id}/escalation-policy/revisions/{revision} |
| `team.write` | Create, rename, and archive teams | human, api_key | POST /api/v1/teams, PATCH /api/v1/teams/{id}, DELETE /api/v1/teams/{id} |

## Agent

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `agent.credential.issue` (dangerous) | Issue instance credentials and provisioner tokens | human, api_key, organization_api_key | POST /api/v1/agents/{slug}/instances, POST /api/v1/agents/{slug}/provisioners |
| `agent.credential.revoke` | Revoke instance credentials and provisioner tokens | human, api_key, organization_api_key | DELETE /api/v1/agent-provisioners/{id}, DELETE /api/v1/agent-credentials/{id} |
| `agent.read` | View agents, their instances, and credential state | human, api_key, organization_api_key | GET /api/v1/agents, GET /api/v1/agents/{slug}, GET /api/v1/tool_catalog, GET /api/v1/tool_catalog/{id} |
| `agent.write` | Create agents, rename agents and instances, and change their status | human, api_key, organization_api_key | POST /api/v1/agents, PATCH /api/v1/agents/{slug}, DELETE /api/v1/agents/{slug}, POST /api/v1/agents/{slug}/restore, PATCH /api/v1/agent_instances/{id} |

## Pipeline

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `pipeline.activate` | Activate and roll back pipeline revisions | human, api_key, organization_api_key | POST /api/v1/request-approval-pipelines/organization/revisions/{revision}/activate, POST /api/v1/request-approval-pipelines/agents/{agent_slug}/revisions/{revision}/activate |
| `pipeline.read` | Read request approval pipelines and their revisions | human, api_key, organization_api_key | GET /api/v1/request-approval-pipelines, GET /api/v1/request-approval-pipelines/organization, GET /api/v1/request-approval-pipelines/organization/revisions, GET /api/v1/request-approval-pipelines/organization/revisions/{revision}, GET /api/v1/request-approval-pipelines/agents/{agent_slug}, GET /api/v1/request-approval-pipelines/agents/{agent_slug}/revisions, GET /api/v1/request-approval-pipelines/agents/{agent_slug}/revisions/{revision} |
| `pipeline.write` | Create and preview request approval pipeline revisions | human, api_key, organization_api_key | POST /api/v1/request-approval-pipelines/organization/preview, POST /api/v1/request-approval-pipelines/organization/revisions, POST /api/v1/request-approval-pipelines/agents/{agent_slug}/preview, POST /api/v1/request-approval-pipelines/agents/{agent_slug}/revisions |

## Escalation path

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `escalation_path.activate` | Activate, roll back, and archive escalation paths | human, api_key, organization_api_key | DELETE /api/v1/escalation-paths/{path_key}, POST /api/v1/escalation-paths/{path_key}/revisions/{revision}/activate |
| `escalation_path.read` | Read escalation paths and their revisions | human, api_key, organization_api_key | GET /api/v1/escalation-paths, GET /api/v1/escalation-paths/{path_key}, GET /api/v1/escalation-paths/{path_key}/revisions, GET /api/v1/escalation-paths/{path_key}/revisions/{revision} |
| `escalation_path.write` | Create escalation paths and their revisions | human, api_key, organization_api_key | POST /api/v1/escalation-paths, POST /api/v1/escalation-paths/{path_key}/revisions |

## Request

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `request.claim` | Claim a pending request while reviewing it | human, api_key | POST /api/v1/requests/{id}/claim, DELETE /api/v1/requests/{id}/claim |
| `request.create` | Create approval requests | agent | POST /api/aap/v1/requests, DELETE /api/aap/v1/requests/{id} |
| `request.decide` | Approve or deny requests routed to you | human, api_key | POST /api/v1/requests/{id}/decision, GET /api/v1/requests/{id}/reviewer-candidates, POST /api/v1/requests/{id}/reviewers |
| `request.decide.unrouted` (dangerous) | Decide requests that were routed to other people (break glass) | human, api_key |  |
| `request.read` | Read approval requests and their outcomes | human, api_key, organization_api_key, agent | GET /api/aap/v1/requests/{id}, GET /api/v1/requests, GET /api/v1/requests/{id}, GET /api/v1/requests/{id}/routing, GET /api/v1/requests/{id}/timeline |
| `request.read.unrouted` | Read requests that were routed to other people, whatever the visibility policy | human, api_key, organization_api_key |  |

## Gateway

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `gateway.call` (hosted edition) | Relay tool calls through the MCP gateway | gateway |  |
| `gateway.read` (hosted edition) | View MCP gateway servers and credentials | human, api_key, organization_api_key | GET /api/v1/agents/{slug}/tool-access |
| `gateway.write` (hosted edition) | Configure MCP gateway servers and credentials | human, api_key, organization_api_key | PUT /api/v1/agents/{slug}/tool-access/{server_slug} |

## Webhook

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `webhook.read` | View webhook endpoints | human, api_key, organization_api_key | GET /api/v1/webhook_endpoints, GET /api/v1/webhook_endpoints/{endpoint_key}, GET /api/v1/webhook_endpoints/{endpoint_key}/revisions, GET /api/v1/webhook_endpoints/{endpoint_key}/revisions/{revision}, GET /api/v1/webhook_endpoints/{endpoint_key}/uses |
| `webhook.write` | Create, edit, rotate, and delete webhook endpoints | human, api_key, organization_api_key | POST /api/v1/webhook_endpoints/{endpoint_key}/revisions, POST /api/v1/webhook_endpoints/{endpoint_key}/revisions/{revision}/activate, POST /api/v1/webhook_endpoints/{endpoint_key}/revisions/{revision}/test, DELETE /api/v1/webhook_endpoints/{endpoint_key}/active, POST /api/v1/webhook_endpoints/{endpoint_key}/rotate_secret |

## Connection

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `connection.read` | View SSO, directory, chat, and domain connections | human, api_key |  |
| `connection.write` (dangerous) | Connect and disconnect SSO, directories, chat apps, and domains | human, api_key |  |

## Audit

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `audit.read` (hosted edition) | Read the audit log | human, api_key, organization_api_key | GET /api/v1/audit, GET /api/v1/audit/{id}, GET /api/v1/audit/event_types |

## Api key

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `api_key.issue` | Mint personal API keys and manage your own | human | POST /api/v1/oauth_authorizations, POST /api/v1/me/api_keys |
| `api_key.read` | List every API key in the organization | human | GET /api/v1/api_keys, GET /api/v1/api_keys/{id} |
| `api_key.revoke` | Revoke any API key in the organization | human | DELETE /api/v1/api_keys/{id} |
| `api_key.organization.issue` (dangerous, hosted edition) | Issue organization API keys | human | POST /api/v1/api_keys, GET /api/v1/api_keys/options |

## Permission policy

| Permission | Description | Held by | Used by |
| --- | --- | --- | --- |
| `permission_policy.read` | Read permission policies and available permissions | human, api_key |  |
| `permission_policy.write` (dangerous) | Grant and revoke permission policies for people and teams | human, api_key | POST /api/v1/members/{id}/permission_policies, PUT /api/v1/members/{id}/permission_policies/{policy_id}, DELETE /api/v1/members/{id}/permission_policies/{policy_id}, POST /api/v1/teams/{id}/permission_policies, PUT /api/v1/teams/{id}/permission_policies/{policy_id}, DELETE /api/v1/teams/{id}/permission_policies/{policy_id}, POST /api/v1/api_keys/{id}/permission_policies, PUT /api/v1/api_keys/{id}/permission_policies/{policy_id}, DELETE /api/v1/api_keys/{id}/permission_policies/{policy_id} |