# Permissions

> What each built-in role can do, and every permission a custom role can hold

Every permission is a `resource:action` pair, such as `agent:create`. A role is a set of these permissions. Docs pages link here by permission name. [Access Control](https://archestra.ai/docs/admin/access-control) explains how roles and per-item grants work together.

## Predefined Roles

Every organization has these four roles. You cannot edit or delete them.

### Admin

Admin holds every permission, including user management, roles, and organization settings.

### Platform Admin

Platform Admin holds every permission except `log:admin`, `guardrailsYell:admin`, `auditLog:admin`, and `member:impersonate`. It manages users, roles, settings, and resources, but sees only its own logs, yells, and audit records and cannot sign in as another member. Because of [No Privilege Escalation](https://archestra.ai/docs/admin/access-control#no-privilege-escalation), it cannot grant a role that holds the withheld permissions.

### Editor

Full access to core resources, but cannot change organization settings or manage users, roles, or identity providers.

| Resource | Actions |
|----------|--------|
| Agents | `read`, `create`, `delete` |
| Skills | `read`, `create`, `delete` |
| Plugins | `read`, `create`, `update`, `delete` |
| Apps | `read`, `create` |
| Guardrails Policy | `read`, `update` |
| LLM Proxy | `read`, `update` |
| LLM Provider API Keys | `read`, `create` |
| LLM Virtual Keys | `read`, `create` |
| LLM Models | `read`, `update` |
| LLM Limits | `read`, `create`, `update`, `delete` |
| LLM Cost Analytics | `read` |
| MCP Gateways | `read`, `create`, `delete` |
| MCP Registry | `read`, `create` |
| MCP Server Installations | `read`, `create`, `update`, `delete` |
| Environments | `read`, `create`, `update`, `delete` |
| Credentials | `read`, `create` |
| Knowledge Sources | `read`, `create`, `update`, `delete`, `query` |
| Chats | `read`, `create`, `update`, `delete`, `full-view` |
| Projects | `read`, `create`, `update`, `delete` |
| LLM & MCP Logs | `read` |
| Guardrails Yells | `read` |
| API Keys | `read`, `create`, `delete` |
| OAuth Clients | `read`, `create` |
| Users | `read` |
| Roles | `read` |
| Teams | `read` |
| Identity Providers | `read` |

### Member

Can manage agents, tools, and chat, with read-only access to most other resources.

| Resource | Actions |
|----------|--------|
| Agents | `read`, `create`, `delete` |
| Skills | `read`, `create`, `delete` |
| Apps | `read`, `create` |
| LLM Proxy | `read` |
| LLM Provider API Keys | `read` |
| LLM Virtual Keys | `read`, `create` |
| LLM Models | `read` |
| MCP Gateways | `read`, `create`, `delete` |
| MCP Registry | `read` |
| MCP Server Installations | `read`, `create`, `delete` |
| Environments | `read` |
| Credentials | `read` |
| Knowledge Sources | `read`, `query` |
| Chats | `read`, `create`, `update`, `delete`, `full-view` |
| Projects | `read`, `create`, `update`, `delete` |
| API Keys | `read`, `create`, `delete` |
| OAuth Clients | `read` |
| Teams | `read` |

## Granular Roles

Each granular role grants one slice of the permissions below, so you can give a user, team, or service account exactly the access it needs without writing a custom role. Assign as many as you like; their permissions add up. You cannot edit or delete them.

| Group | Role | Identifier | Permissions |
|-------|------|------------|-------------|
| Agents | Agent Reader | `fixed:agents:reader` | `agent:read` |
| Agents | Agent Writer | `fixed:agents:writer` | `agent:read`, `agent:create`, `agent:delete` |
| Skills | Skill Reader | `fixed:skills:reader` | `skill:read` |
| Skills | Skill Writer | `fixed:skills:writer` | `skill:read`, `skill:create`, `skill:delete` |
| Plugins | Plugin Reader | `fixed:plugins:reader` | `plugin:read` |
| Plugins | Plugin Writer | `fixed:plugins:writer` | `plugin:read`, `plugin:create`, `plugin:update`, `plugin:delete` |
| Apps | App Reader | `fixed:apps:reader` | `app:read` |
| Apps | App Writer | `fixed:apps:writer` | `app:read`, `app:create` |
| Guardrails | Guardrails Reader | `fixed:guardrails:reader` | `guardrailsPolicy:read` |
| Guardrails | Guardrails Writer | `fixed:guardrails:writer` | `guardrailsPolicy:read`, `guardrailsPolicy:update` |
| Chat & Projects | Chat User | `fixed:chat:user` | `chat:read`, `chat:create`, `chat:update`, `chat:delete` |
| Chat & Projects | Chat Full View | `fixed:chat:full-view` | `chat:read`, `chat:full-view` |
| Chat & Projects | Project Reader | `fixed:projects:reader` | `project:read` |
| Chat & Projects | Project Writer | `fixed:projects:writer` | `project:read`, `project:create`, `project:update`, `project:delete` |
| Knowledge | Knowledge Reader | `fixed:knowledge:reader` | `knowledgeSource:read`, `knowledgeSource:query` |
| Knowledge | Knowledge Writer | `fixed:knowledge:writer` | `knowledgeSource:read`, `knowledgeSource:create`, `knowledgeSource:update`, `knowledgeSource:delete`, `knowledgeSource:query` |
| MCP | MCP Gateway Reader | `fixed:mcp-gateways:reader` | `mcpGateway:read` |
| MCP | MCP Gateway Writer | `fixed:mcp-gateways:writer` | `mcpGateway:read`, `mcpGateway:create`, `mcpGateway:delete` |
| MCP | MCP Registry Reader | `fixed:mcp-registry:reader` | `mcpRegistry:read` |
| MCP | MCP Registry Writer | `fixed:mcp-registry:writer` | `mcpRegistry:read`, `mcpRegistry:create` |
| MCP | MCP Server Reader | `fixed:mcp-servers:reader` | `mcpServerInstallation:read` |
| MCP | MCP Server Writer | `fixed:mcp-servers:writer` | `mcpServerInstallation:read`, `mcpServerInstallation:create`, `mcpServerInstallation:update`, `mcpServerInstallation:delete` |
| Environments | Environment Reader | `fixed:environments:reader` | `environment:read` |
| Environments | Environment Writer | `fixed:environments:writer` | `environment:read`, `environment:create`, `environment:update`, `environment:delete` |
| LLM | LLM Proxy Reader | `fixed:llm-proxy:reader` | `llmProxy:read` |
| LLM | LLM Proxy Writer | `fixed:llm-proxy:writer` | `llmProxy:read`, `llmProxy:update` |
| LLM | Provider Key Reader | `fixed:llm-provider-keys:reader` | `llmProviderApiKey:read` |
| LLM | Provider Key Writer | `fixed:llm-provider-keys:writer` | `llmProviderApiKey:read`, `llmProviderApiKey:create` |
| LLM | Virtual Key Reader | `fixed:llm-virtual-keys:reader` | `llmVirtualKey:read` |
| LLM | Virtual Key Writer | `fixed:llm-virtual-keys:writer` | `llmVirtualKey:read`, `llmVirtualKey:create` |
| LLM | Model Reader | `fixed:llm-models:reader` | `llmModel:read` |
| LLM | Model Writer | `fixed:llm-models:writer` | `llmModel:read`, `llmModel:update` |
| LLM Costs & Limits | Cost Reader | `fixed:llm-costs:reader` | `llmCost:read` |
| LLM Costs & Limits | Limit Reader | `fixed:llm-limits:reader` | `llmLimit:read` |
| LLM Costs & Limits | Limit Writer | `fixed:llm-limits:writer` | `llmLimit:read`, `llmLimit:create`, `llmLimit:update`, `llmLimit:delete` |
| LLM Costs & Limits | Cost Export Reader | `fixed:cost-exports:reader` | `costExport:read` |
| LLM Costs & Limits | Cost Export Writer | `fixed:cost-exports:writer` | `costExport:read`, `costExport:create`, `costExport:update`, `costExport:delete` |
| Logs & Audit | Log Reader | `fixed:logs:reader` | `log:read`, `guardrailsYell:read` |
| Logs & Audit | Log Admin | `fixed:logs:admin` | `log:read`, `log:admin`, `guardrailsYell:read`, `guardrailsYell:admin` |
| Logs & Audit | Yell Reader | `fixed:yells:reader` | `guardrailsYell:read` |
| Logs & Audit | Yell Admin | `fixed:yells:admin` | `guardrailsYell:read`, `guardrailsYell:admin` |
| Logs & Audit | Audit Log Reader | `fixed:audit-log:reader` | `auditLog:read` |
| Logs & Audit | Audit Log Admin | `fixed:audit-log:admin` | `auditLog:read`, `auditLog:admin` |
| Users & Teams | User Reader | `fixed:users:reader` | `member:read` |
| Users & Teams | User Writer | `fixed:users:writer` | `member:read`, `member:create`, `member:update`, `member:delete` |
| Users & Teams | User Impersonator | `fixed:users:impersonator` | `member:read`, `member:impersonate` |
| Users & Teams | Team Reader | `fixed:teams:reader` | `team:read` |
| Users & Teams | Team Writer | `fixed:teams:writer` | `team:read`, `team:create`, `team:update`, `team:delete` |
| Roles & Access | Role Reader | `fixed:roles:reader` | `ac:read` |
| Roles & Access | Role Writer | `fixed:roles:writer` | `ac:read`, `ac:create`, `ac:update`, `ac:delete` |
| Roles & Access | Access Policy Reader | `fixed:access-policies:reader` | `accessPolicies:read` |
| Roles & Access | Access Policy Writer | `fixed:access-policies:writer` | `accessPolicies:read`, `accessPolicies:update` |
| Roles & Access | Identity Provider Reader | `fixed:identity-providers:reader` | `identityProvider:read` |
| Roles & Access | Identity Provider Writer | `fixed:identity-providers:writer` | `identityProvider:read`, `identityProvider:create`, `identityProvider:update`, `identityProvider:delete` |
| API Access | API Key Reader | `fixed:api-keys:reader` | `apiKey:read` |
| API Access | API Key Writer | `fixed:api-keys:writer` | `apiKey:read`, `apiKey:create`, `apiKey:delete` |
| API Access | Service Account Reader | `fixed:service-accounts:reader` | `serviceAccount:read` |
| API Access | Service Account Writer | `fixed:service-accounts:writer` | `serviceAccount:read`, `serviceAccount:create` |
| API Access | OAuth Client Reader | `fixed:oauth-clients:reader` | `oauthClient:read` |
| API Access | OAuth Client Writer | `fixed:oauth-clients:writer` | `oauthClient:read`, `oauthClient:create` |
| API Access | Credential Reader | `fixed:credentials:reader` | `credential:read` |
| API Access | Credential Writer | `fixed:credentials:writer` | `credential:read`, `credential:create` |
| Organization | Organization Settings Reader | `fixed:organization-settings:reader` | `organizationSettings:read` |
| Organization | Organization Settings Writer | `fixed:organization-settings:writer` | `organizationSettings:read`, `organizationSettings:update` |

<span id="llm-api-permissions"></span>

## Available Permissions

A [custom role](https://archestra.ai/docs/admin/access-control#custom-roles) can hold any of these permissions. To grant an action on a single item, such as one agent, see [Granular Access Control](https://archestra.ai/docs/admin/access-control#granular-access-control).

### Agents

| Permission | Description |
|------------|-------------|
| <span id="agent:read"></span>`agent:read` | Open Agents, and use the code sandboxes and files of agents you can use |
| <span id="agent:create"></span>`agent:create` | Create new agents |
| <span id="agent:delete"></span>`agent:delete` | Open the trash of deleted agents |
| <span id="skill:read"></span>`skill:read` | Open Skills |
| <span id="skill:create"></span>`skill:create` | Create new agent skills |
| <span id="skill:delete"></span>`skill:delete` | Permanently delete skills from the trash |
| <span id="plugin:read"></span>`plugin:read` | View plugins and their file metadata |
| <span id="plugin:create"></span>`plugin:create` | Create plugins |
| <span id="plugin:update"></span>`plugin:update` | No standalone effect; editing a plugin requires a Can edit or Full access grant on that plugin |
| <span id="plugin:delete"></span>`plugin:delete` | No standalone effect; deleting a plugin requires a Full access grant on that plugin |
| <span id="app:read"></span>`app:read` | Open Apps |
| <span id="app:create"></span>`app:create` | Create new MCP Apps |
| <span id="guardrailsPolicy:read"></span>`guardrailsPolicy:read` | View Guardrails policy, batteries, and coverage |
| <span id="guardrailsPolicy:update"></span>`guardrailsPolicy:update` | Validate and edit Guardrails policy and manage batteries |

### MCP

| Permission | Description |
|------------|-------------|
| <span id="mcpGateway:read"></span>`mcpGateway:read` | Open MCP Gateways |
| <span id="mcpGateway:create"></span>`mcpGateway:create` | Create new MCP gateways |
| <span id="mcpGateway:delete"></span>`mcpGateway:delete` | Open the trash of deleted MCP gateways |
| <span id="mcpRegistry:read"></span>`mcpRegistry:read` | Open the MCP registry and use its built-in servers |
| <span id="mcpRegistry:create"></span>`mcpRegistry:create` | Add servers to the MCP registry |
| <span id="mcpServerInstallation:read"></span>`mcpServerInstallation:read` | View installed MCP servers and their status |
| <span id="mcpServerInstallation:create"></span>`mcpServerInstallation:create` | Install MCP servers from the registry |
| <span id="mcpServerInstallation:update"></span>`mcpServerInstallation:update` | Modify installed MCP server configuration |
| <span id="mcpServerInstallation:delete"></span>`mcpServerInstallation:delete` | Uninstall, view deleted, and restore MCP servers within your access |

### LLM

| Permission | Description |
|------------|-------------|
| <span id="llmProxy:read"></span>`llmProxy:read` | View the LLM Proxy and its connection details |
| <span id="llmProxy:update"></span>`llmProxy:update` | Modify LLM Proxy configuration |
| <span id="llmProviderApiKey:read"></span>`llmProviderApiKey:read` | Open LLM provider API keys |
| <span id="llmProviderApiKey:create"></span>`llmProviderApiKey:create` | Add new LLM provider API keys |
| <span id="llmVirtualKey:read"></span>`llmVirtualKey:read` | Open LLM virtual keys |
| <span id="llmVirtualKey:create"></span>`llmVirtualKey:create` | Create LLM virtual keys |
| <span id="llmModel:read"></span>`llmModel:read` | View synced LLM models and capabilities |
| <span id="llmModel:update"></span>`llmModel:update` | Sync the model catalog and see every model, including ones not shared with you |
| <span id="llmLimit:read"></span>`llmLimit:read` | View token usage limits |
| <span id="llmLimit:create"></span>`llmLimit:create` | Create new usage limits |
| <span id="llmLimit:update"></span>`llmLimit:update` | Modify existing usage limits |
| <span id="llmLimit:delete"></span>`llmLimit:delete` | Remove usage limits |
| <span id="llmCost:read"></span>`llmCost:read` | View organization-wide LLM usage cost statistics and analytics |
| <span id="costExport:read"></span>`costExport:read` | View scheduled cost exports and their run status |
| <span id="costExport:create"></span>`costExport:create` | Schedule cost exports to a blob provider |
| <span id="costExport:update"></span>`costExport:update` | Change, pause, resume, and run cost exports |
| <span id="costExport:delete"></span>`costExport:delete` | Delete cost exports |

### Other

| Permission | Description |
|------------|-------------|
| <span id="chat:read"></span>`chat:read` | View and access chat conversations |
| <span id="chat:create"></span>`chat:create` | Start new chat conversations |
| <span id="chat:update"></span>`chat:update` | Edit chat messages and conversation settings |
| <span id="chat:delete"></span>`chat:delete` | Delete chat conversations |
| <span id="chat:full-view"></span>`chat:full-view` | Show the full chat: the agent picker, model and API key selectors, and expandable tool calls. Without it, chat shows a simpler view |
| <span id="scheduledTask:read"></span><span id="project:read"></span>`project:read` | View projects, their schedules, and your own sessions inside them |
| <span id="scheduledTask:create"></span><span id="project:create"></span>`project:create` | Create projects and schedules, and trigger schedule runs |
| <span id="scheduledTask:update"></span><span id="project:update"></span>`project:update` | Edit project descriptions, instructions, sharing, and schedules |
| <span id="scheduledTask:delete"></span><span id="project:delete"></span>`project:delete` | Delete projects and schedules |
| <span id="knowledgeSource:read"></span>`knowledgeSource:read` | View Knowledge Bases and Connectors |
| <span id="knowledgeSource:create"></span>`knowledgeSource:create` | Create Knowledge Bases and Connectors |
| <span id="knowledgeSource:update"></span>`knowledgeSource:update` | Modify Knowledge Bases and Connectors |
| <span id="knowledgeSource:delete"></span>`knowledgeSource:delete` | Delete Knowledge Bases and Connectors, view the deleted ones, and restore them |
| <span id="knowledgeSource:query"></span>`knowledgeSource:query` | Query knowledge sources for information retrieval |

### Logs

| Permission | Description |
|------------|-------------|
| <span id="log:read"></span>`log:read` | View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization |
| <span id="log:admin"></span>`log:admin` | View every LLM, MCP, and Guardrails consult log in your organization (also requires Read) |
| <span id="guardrailsYell:read"></span>`guardrailsYell:read` | View and resolve the Guardrails yells of your own sessions |
| <span id="guardrailsYell:admin"></span>`guardrailsYell:admin` | View and resolve every Guardrails yell in your organization (also requires Read) |
| <span id="auditLog:read"></span>`auditLog:read` | View audit log records of your own administrative actions |
| <span id="auditLog:admin"></span>`auditLog:admin` | View every audit event in your organization (also requires Read) |

### Administration

| Permission | Description |
|------------|-------------|
| <span id="accessPolicies:read"></span>`accessPolicies:read` | View access policies for all resource types |
| <span id="accessPolicies:update"></span>`accessPolicies:update` | Edit access policies and grant access across all resource types |
| <span id="member:read"></span>`member:read` | View organization members and their roles |
| <span id="member:create"></span>`member:create` | Add new members to the organization and manage invitations |
| <span id="member:update"></span>`member:update` | Change member roles and settings |
| <span id="member:delete"></span>`member:delete` | Remove members from the organization |
| <span id="member:impersonate"></span>`member:impersonate` | Temporarily sign in as another member to see the app with their access (role debugging) |
| <span id="ac:read"></span>`ac:read` | View custom roles and their permissions |
| <span id="ac:create"></span>`ac:create` | Create new custom roles |
| <span id="ac:update"></span>`ac:update` | Modify custom role permissions |
| <span id="ac:delete"></span>`ac:delete` | Delete custom roles |
| <span id="team:read"></span>`team:read` | View teams and their members |
| <span id="team:create"></span>`team:create` | Create new teams |
| <span id="team:update"></span>`team:update` | Modify team settings |
| <span id="team:delete"></span>`team:delete` | Delete teams |
| <span id="identityProvider:read"></span>`identityProvider:read` | View identity provider configurations (SSO) |
| <span id="identityProvider:create"></span>`identityProvider:create` | Set up new identity providers |
| <span id="identityProvider:update"></span>`identityProvider:update` | Modify identity provider settings |
| <span id="identityProvider:delete"></span>`identityProvider:delete` | Remove identity providers |
| <span id="apiKey:read"></span>`apiKey:read` | View API keys |
| <span id="apiKey:create"></span>`apiKey:create` | Create API keys |
| <span id="apiKey:delete"></span>`apiKey:delete` | Delete API keys |
| <span id="mcpOauthClient:read"></span><span id="llmOauthClient:read"></span><span id="oauthClient:read"></span>`oauthClient:read` | Open OAuth client registrations |
| <span id="mcpOauthClient:create"></span><span id="llmOauthClient:create"></span><span id="oauthClient:create"></span>`oauthClient:create` | Create OAuth client registrations |
| <span id="serviceAccount:read"></span>`serviceAccount:read` | Open Service Accounts |
| <span id="serviceAccount:create"></span>`serviceAccount:create` | Create service accounts |
| <span id="credential:read"></span>`credential:read` | Open Credentials |
| <span id="credential:create"></span>`credential:create` | Create saved credentials |
| <span id="environment:read"></span>`environment:read` | View and list deployment environments |
| <span id="environment:create"></span>`environment:create` | Create deployment environments |
| <span id="environment:update"></span>`environment:update` | Modify deployment environments, including the org default environment |
| <span id="environment:delete"></span>`environment:delete` | Delete deployment environments |
| <span id="organizationSettings:read"></span>`organizationSettings:read` | View every organization settings page, including messaging channels |
| <span id="organizationSettings:update"></span>`organizationSettings:update` | Change organization settings, messaging channels, and site notifications |
