# Permissions Reference

> > This page is auto-generated. Do not edit manually — run `pnpm generate-permissions-page` to regenerate.

# Permissions Reference

> This page is auto-generated. Do not edit manually — run `pnpm generate-permissions-page` to regenerate.

Complete list of all IAM permission actions, grouped by module. Use these strings in the `action` field of a policy statement.

See [IAM & Policies](./modules/iam) for how policies are evaluated.

## Activity

| Permission | Description |
| ---------- | ----------- |
| `activity:ListActivity` | List activity feed entries in a project |

## Actors

| Permission | Description |
| ---------- | ----------- |
| `actors:ListActors` | List actors in a project |
| `actors:CreateActor` | Create a new actor |
| `actors:GetActor` | Get an actor by ID |
| `actors:UpdateActor` | Update an actor |
| `actors:DeleteActor` | Delete an actor |
| `actors:GetActor` | Get an actor's tags |
| `actors:UpdateActor` | Replace an actor's tags |
| `actors:UpdateActor` | Merge an actor's tags |

## Agents

| Permission | Description |
| ---------- | ----------- |
| `agents:CreateAgent` | Create a new agent |
| `agents:ListAgents` | List agents in a project |
| `agents:GetAgent` | Get an agent by ID |
| `agents:UpdateAgent` | Update an agent |
| `agents:DeleteAgent` | Delete an agent |
| `agents:CreateAgentGeneration` | Run a generation for an agent |
| `agents:CreateAgentGeneration` | Submit tool outputs to resume a paused generation |
| `agents:ListAgentVersions` | List an agent's archived config versions |
| `agents:GetAgentVersion` | Get one archived agent config version |
| `agents:RestoreAgentVersion` | Restore an archived agent config as a new version |
| `agents:SetAgentRelease` | Set or replace an agent's staged rollout |
| `agents:SetAgentRelease` | Promote the canary version to stable and end the rollout |
| `agents:SetAgentRelease` | Roll traffic back to the stable version and end the rollout |
| `agents:UpdateAgent` | Partially update an agent |

## Ai Providers

| Permission | Description |
| ---------- | ----------- |
| `ai-providers:ListAiProviders` | List AI providers in a project |
| `ai-providers:CreateAiProvider` | Create an AI provider |
| `ai-providers:GetAiProvider` | Get an AI provider by ID |
| `ai-providers:UpdateAiProvider` | Update an AI provider |
| `ai-providers:DeleteAiProvider` | Delete an AI provider |
| `ai-providers:ListAiProviderModels` | List the models an AI provider can run |
| `ai-providers:GetAiProviderPrices` | List per-provider price overrides for an AI provider |
| `ai-providers:ManageAiProviderPrices` | Upsert per-provider price overrides for an AI provider |

## Api Keys

| Permission | Description |
| ---------- | ----------- |
| `api-keys:ListApiKeys` | List API keys owned by the caller |
| `api-keys:CreateApiKey` | Create a new API key |
| `api-keys:GetApiKey` | Get an API key by ID (owner only) |
| `api-keys:UpdateApiKey` | Update an API key's policy (owner only) |
| `api-keys:DeleteApiKey` | Delete an API key (owner only) |

## Approvals

| Permission | Description |
| ---------- | ----------- |
| `approvals:ListApprovals` | List approval items in a project |
| `approvals:GetApproval` | Get an approval item by ID with its full evidence |
| `approvals:ListApprovalRecurrences` | List recurring approval groups (same dedup_key) in a project |
| `approvals:ResolveApproval` | Approve an approval item, optionally with edited arguments |
| `approvals:ResolveApproval` | Reject an approval item with a required reason |

## Audit

| Permission | Description |
| ---------- | ----------- |
| `audit:ListAuditEntries` | List audit-log entries in a project |
| `audit:GetAuditEntry` | Get a single audit-log entry by ID |
| `audit:ExportAuditEntries` | Export a project's audit-log entries as NDJSON |

## Chains

| Permission | Description |
| ---------- | ----------- |
| `chains:ListChains` | List continuation chains in a project |
| `chains:GetChain` | Get a continuation chain by ID |

## Chats

| Permission | Description |
| ---------- | ----------- |
| `chats:CreateChat` | Create a new chat |
| `chats:ListChats` | List chats in a project |
| `chats:GetChat` | Get a chat by ID |
| `chats:DeleteChat` | Delete a chat |
| `chats:CreateChatCompletion` | Generate a chat completion, stateless or against a stored chat |

## Conversations

| Permission | Description |
| ---------- | ----------- |
| `conversations:ListConversations` | List conversations in a project |
| `conversations:CreateConversation` | Create a new conversation |
| `conversations:GetConversation` | Get a conversation by ID |
| `conversations:UpdateConversation` | Update a conversation's status |
| `conversations:DeleteConversation` | Delete a conversation |
| `conversations:GetConversation` | List messages in a conversation |
| `conversations:UpdateConversation` | Add a message to a conversation |
| `conversations:UpdateConversation` | Remove a message from a conversation |
| `conversations:GenerateConversationMessage` | Generate the next message in a conversation |
| `conversations:GetConversation` | Get a conversation's tags |
| `conversations:UpdateConversation` | Replace a conversation's tags |
| `conversations:UpdateConversation` | Merge a conversation's tags |

## Documents

| Permission | Description |
| ---------- | ----------- |
| `documents:ListDocuments` | List documents in a project |
| `documents:CreateDocument` | Create a new document |
| `documents:GetDocument` | Get a document by ID |
| `documents:GetDocument` | Get a document's lightweight ingestion status |
| `documents:UpdateDocument` | Update a document |
| `documents:DeleteDocument` | Delete a document |
| `documents:IngestDocument` | Ingest a file (PDF or text) into a chunked document |
| `documents:IngestDocument` | Re-ingest an existing document from its source file |
| `documents:GetDocument` | Get a document's tags |
| `documents:UpdateDocument` | Replace a document's tags |
| `documents:UpdateDocument` | Merge a document's tags |

### Resource Identifiers

| Pattern | Description |
| ------- | ----------- |
| `soat:{project_id}:document:{id}` | Specific document by ID |
| `soat:{project_id}:document:{path}` | Document at a logical path |
| `soat:{project_id}:document:/prefix/*` | All documents under a path prefix |
| `soat:{project_id}:document:*` | All documents in a project |

## Embeddings

| Permission | Description |
| ---------- | ----------- |
| `embeddings:CreateEmbeddings` | Generate text embeddings using the server's embedding model |

## Evaluations

| Permission | Description |
| ---------- | ----------- |
| `evaluations:ListDatasets` | List datasets in a project |
| `evaluations:CreateDataset` | Create a dataset |
| `evaluations:GetDataset` | Get a dataset by ID |
| `evaluations:CreateDataset` | Update a dataset's name or description |
| `evaluations:DeleteDataset` | Delete a dataset, its items, and the evals bound to it |
| `evaluations:ListDatasets` | List the test cases in a dataset |
| `evaluations:CreateDataset` | Add a test case to a dataset |
| `evaluations:CreateDataset` | Curate a completed generation into a dataset item (also requires generations:GetGeneration) |
| `evaluations:CreateDataset` | Update a test case in a dataset |
| `evaluations:CreateDataset` | Delete a test case from a dataset |
| `evaluations:ListEvals` | List evals in a project |
| `evaluations:CreateEval` | Create an eval binding an agent, a dataset, and scorers |
| `evaluations:GetEval` | Get an eval by ID |
| `evaluations:CreateEval` | Update an eval's agent, dataset, scorers, or pass threshold |
| `evaluations:DeleteEval` | Delete an eval and its runs |
| `evaluations:RunEval` | Run an eval against its dataset and score every item |
| `evaluations:ListEvals` | List an eval's runs |
| `evaluations:GetEval` | Get an eval run's status and aggregate scores |
| `evaluations:ListEvals` | List the per-item results of an eval run |
| `evaluations:RunEval` | Cancel a queued or running eval run |

## Exceptions

| Permission | Description |
| ---------- | ----------- |
| `exceptions:ListExceptions` | List exception items in a project |
| `exceptions:GetException` | Get an exception item by ID with its full detail |
| `exceptions:AcknowledgeException` | Acknowledge an exception item (someone is on it) |
| `exceptions:ResolveException` | Resolve an exception item with an optional note |

## Files

| Permission | Description |
| ---------- | ----------- |
| `files:GetFile` | List files in a project |
| `files:CreateFile` | Create a metadata-only file record |
| `files:UploadFile` | Upload a file (multipart) |
| `files:UploadFile` | Upload a file (base64-encoded) |
| `files:GetFile` | Get file metadata by ID |
| `files:DownloadFile` | Download file content |
| `files:DownloadFile` | Download file content as base64 |
| `files:UpdateFileMetadata` | Update file metadata |
| `files:DeleteFile` | Delete a file |
| `files:GetFile` | Get a file's tags |
| `files:UpdateFileMetadata` | Replace a file's tags |
| `files:UpdateFileMetadata` | Merge a file's tags |
| `files:UploadFile` | Create a presigned upload URL |

### Resource Identifiers

| Pattern | Description |
| ------- | ----------- |
| `soat:{project_id}:file:{id}` | Specific file by ID |
| `soat:{project_id}:file:/path/to/file.ext` | File at an exact logical path |
| `soat:{project_id}:file:/prefix/*` | All files under a path prefix |
| `soat:{project_id}:file:*` | All files in a project |

## Formations

| Permission | Description |
| ---------- | ----------- |
| `formations:ValidateFormation` | Validate a formation template |
| `formations:PlanFormation` | Plan a formation deployment |
| `formations:CreateFormation` | Create a new agent formation stack |
| `formations:ListFormations` | List formation stacks in a project |
| `formations:GetFormation` | Get a formation stack by ID |
| `formations:UpdateFormation` | Update a formation stack by applying a new template |
| `formations:DeleteFormation` | Delete a formation stack and all its managed resources |
| `formations:ListFormationEvents` | List operation events for a formation stack |

## Generations

| Permission | Description |
| ---------- | ----------- |
| `generations:ListGenerations` | List generations, optionally filtered by agent, trace, or status |
| `generations:GetGeneration` | Get a generation record by ID |
| `generations:GetGeneration` | Read a generation's turn as an ordered transcript of steps, tool calls and results (also requires traces:GetTrace) |
| `generations:UpdateGeneration` | Attach caller-supplied metadata to a generation record |
| `generations:PurgeGenerationContent` | Purge a generation's content, clearing its metadata, error and derived summaries |

## Guardrails

| Permission | Description |
| ---------- | ----------- |
| `guardrails:CreateGuardrail` | Create a guardrail |
| `guardrails:ListGuardrails` | List guardrails in a project |
| `guardrails:GetGuardrail` | Get a guardrail by ID |
| `guardrails:UpdateGuardrail` | Update a guardrail |
| `guardrails:DeleteGuardrail` | Delete a guardrail |
| `guardrails:ListGuardrailVersions` | List a guardrail's archived config versions |
| `guardrails:GetGuardrailVersion` | Fetch one archived guardrail config version |
| `guardrails:RestoreGuardrailVersion` | Restore an archived guardrail config as a new version |
| `guardrails:EvaluateGuardrail` | Dry-run evaluate a guardrail without executing |
| `guardrails:DetachGuardrail` | Remove a guardrail from a project, agent, or tool guardrail_ids list |

## Ingestion Rules

| Permission | Description |
| ---------- | ----------- |
| `ingestion-rules:ListIngestionRules` | List ingestion rules in a project |
| `ingestion-rules:CreateIngestionRule` | Create a new ingestion rule |
| `ingestion-rules:GetIngestionRule` | Get an ingestion rule by ID |
| `ingestion-rules:UpdateIngestionRule` | Update an ingestion rule |
| `ingestion-rules:DeleteIngestionRule` | Delete an ingestion rule |

## Knowledge

| Permission | Description |
| ---------- | ----------- |
| `knowledge:SearchKnowledge` | Search across documents and knowledge sources |

## Memories

| Permission | Description |
| ---------- | ----------- |
| `memories:ListMemories` | List memory configurations in a project |
| `memories:CreateMemory` | Create a new memory configuration |
| `memories:GetMemory` | Get a memory configuration by ID |
| `memories:UpdateMemory` | Update a memory configuration |
| `memories:DeleteMemory` | Delete a memory configuration |
| `memories:ListMemoryEntries` | List entries in a memory |
| `memories:CreateMemoryEntry` | Create a new memory entry |
| `memories:GetMemoryEntry` | Get a memory entry by ID |
| `memories:UpdateMemoryEntry` | Update a memory entry |
| `memories:DeleteMemoryEntry` | Delete a memory entry |

## Model Routes

| Permission | Description |
| ---------- | ----------- |
| `model-routes:ListModelRoutes` | List model routes in a project |
| `model-routes:CreateModelRoute` | Create a model route |
| `model-routes:GetModelRoute` | Get a model route by ID |
| `model-routes:UpdateModelRoute` | Update a model route's name, targets, retry classes, or breaker configuration |
| `model-routes:DeleteModelRoute` | Delete a model route |

## Orchestrations

| Permission | Description |
| ---------- | ----------- |
| `orchestrations:CreateOrchestration` | Create an orchestration |
| `orchestrations:ValidateOrchestration` | Statically validate an orchestration graph |
| `orchestrations:ListOrchestrations` | List orchestrations in a project |
| `orchestrations:GetOrchestration` | Get an orchestration by ID |
| `orchestrations:UpdateOrchestration` | Update an orchestration |
| `orchestrations:DeleteOrchestration` | Delete an orchestration |
| `orchestrations:ListOrchestrationVersions` | List an orchestration's archived graph versions |
| `orchestrations:GetOrchestrationVersion` | Fetch one archived orchestration graph version |
| `orchestrations:RestoreOrchestrationVersion` | Restore an archived orchestration graph as a new version |
| `orchestrations:StartRun` | Start a new orchestration run |
| `orchestrations:ListRuns` | List runs for an orchestration |
| `orchestrations:GetRun` | Get an orchestration run by ID |
| `orchestrations:CancelRun` | Cancel a running or paused orchestration run |
| `orchestrations:SubmitHumanInput` | Submit human input to a paused orchestration run |
| `orchestrations:ResumeRun` | Resume a paused orchestration run from its last checkpoint |
| `orchestrations:GetQueueStats` | Read orchestration queue depth and claim-latency metrics |

## Policies

| Permission | Description |
| ---------- | ----------- |
| `policies:ListPolicies` | List all policies (admin only) |
| `policies:CreatePolicy` | Create a new policy (admin only) |
| `policies:GetPolicy` | Get a policy by ID (admin only) |
| `policies:UpdatePolicy` | Update a policy (admin only) |
| `policies:DeletePolicy` | Delete a policy (admin only) |

## Projects

| Permission | Description |
| ---------- | ----------- |
| `projects:ListProjects` | List projects the caller can access |
| `projects:CreateProject` | Create a new project (admin only) |
| `projects:GetProject` | Get a project by ID |
| `projects:UpdateProject` | Rename a project (admin only) |
| `projects:DeleteProject` | Delete a project (admin only) |
| `projects:GetProjectPrices` | List a project's per-provider-slug price rows |
| `projects:ManageProjectPrices` | Upsert a project's per-provider-slug price rows |

## Quotas

| Permission | Description |
| ---------- | ----------- |
| `quotas:ListQuotas` | List quotas in a project |
| `quotas:CreateQuota` | Create a quota |
| `quotas:GetQuota` | Get a quota by ID, including current window usage |
| `quotas:UpdateQuota` | Update a quota's limit or mode |
| `quotas:DeleteQuota` | Delete a quota and its counters |

## Secrets

| Permission | Description |
| ---------- | ----------- |
| `secrets:ListSecrets` | List secrets in a project |
| `secrets:CreateSecret` | Create a new secret |
| `secrets:GetSecret` | Get a secret by ID (value is never returned) |
| `secrets:UpdateSecret` | Update a secret's value |
| `secrets:DeleteSecret` | Delete a secret |

## Sessions

| Permission | Description |
| ---------- | ----------- |
| `agents:CreateSession` | Create a new session for an agent |
| `agents:ListSessions` | List sessions |
| `agents:GetSession` | Get a session |
| `agents:UpdateSession` | Update session name, status, or tags |
| `agents:DeleteSession` | Delete a session |
| `agents:CreateSession` | Branch a new session from a point in a session's history (also requires agents:GetSession) |
| `agents:GetSession` | List the sessions forked from a session |
| `agents:SendSessionMessage` | Save a user message or trigger generation |
| `agents:SendSessionMessage` | Generate an assistant response in a session |
| `agents:SubmitSessionToolOutputs` | Submit tool outputs for client tools in a session |
| `agents:GetSession` | Get a session's tags |
| `agents:UpdateSession` | Replace a session's tags |
| `agents:UpdateSession` | Merge a session's tags |

## Tasks

| Permission | Description |
| ---------- | ----------- |
| `tasks:CreateTask` | Create a task bound to a workflow |
| `tasks:ListTasks` | List tasks (board query) |
| `tasks:GetTask` | Get a task by ID |
| `tasks:GetTask` | Get a task's transition history |
| `tasks:UpdateTask` | Update a task's payload, title, or assignee |
| `tasks:TransitionTask` | Fire a named transition on a task |
| `tasks:DeleteTask` | Delete a task |

## Tools

| Permission | Description |
| ---------- | ----------- |
| `tools:CreateTool` | Create a tool |
| `tools:ListTools` | List tools in a project |
| `tools:GetTool` | Get a tool by ID |
| `tools:UpdateTool` | Update a tool |
| `tools:DeleteTool` | Delete a tool |
| `tools:CallTool` | Call (invoke) a tool directly |

## Traces

| Permission | Description |
| ---------- | ----------- |
| `traces:ListTraces` | List execution traces in a project |
| `traces:GetTrace` | Get a trace by ID |
| `traces:GetTraceTree` | Get the full execution tree for a trace |
| `traces:PurgeTraceContent` | Purge a trace's content, deleting its steps file from storage and cascading to descendants and generations |

## Triggers

| Permission | Description |
| ---------- | ----------- |
| `triggers:ListTriggers` | List triggers in a project |
| `triggers:CreateTrigger` | Create a new trigger |
| `triggers:GetTrigger` | Get a trigger by ID |
| `triggers:UpdateTrigger` | Update a trigger |
| `triggers:DeleteTrigger` | Delete a trigger |
| `triggers:FireTrigger` | Fire a trigger manually |
| `triggers:GetTriggerSecret` | Retrieve the signing secret for a webhook trigger |
| `triggers:RotateTriggerSecret` | Rotate the signing secret for a webhook trigger |
| `triggers:ListTriggerFirings` | List firings for a trigger |
| `triggers:GetTriggerFiring` | Get details of a specific trigger firing |

## Usage

| Permission | Description |
| ---------- | ----------- |
| `usage:ListUsageMeters` | List raw usage-meter rows, optionally filtered by agent or generation |
| `usage:GetReceipt` | Get a billing receipt for a generation |
| `usage:GetUsage` | Read a project's aggregated usage rollup |
| `usage:ListThresholds` | List a project's usage alert thresholds |
| `usage:ManageThresholds` | Create a usage alert threshold |
| `usage:ManageThresholds` | Delete a usage alert threshold |
| `usage:GetPriceBook` | Read the global price book |
| `usage:ManagePriceBook` | Upsert price-book rows (admin only) |

## Users

| Permission | Description |
| ---------- | ----------- |
| `users:ListUsers` | List all users |
| `users:CreateUser` | Create a new user |
| `users:GetUser` | Get a user by ID |
| `users:DeleteUser` | Delete a user |
| `users:AttachUserPolicies` | Replace the full set of policies attached to a user |

## Webhooks

| Permission | Description |
| ---------- | ----------- |
| `webhooks:ListWebhooks` | List webhooks in a project |
| `webhooks:CreateWebhook` | Create a new webhook |
| `webhooks:GetWebhook` | Get a webhook by ID |
| `webhooks:UpdateWebhook` | Update a webhook |
| `webhooks:DeleteWebhook` | Delete a webhook |
| `webhooks:RotateWebhookSecret` | Rotate the signing secret for a webhook |
| `webhooks:GetWebhookSecret` | Retrieve the signing secret for a webhook |
| `webhooks:ListWebhookDeliveries` | List delivery attempts for a webhook |
| `webhooks:GetWebhookDelivery` | Get details of a specific webhook delivery |
| `webhooks:RedeliverWebhookDelivery` | Queue a stored delivery to be sent again |

## Workflows

| Permission | Description |
| ---------- | ----------- |
| `workflows:CreateWorkflow` | Create a workflow definition |
| `workflows:ListWorkflows` | List workflows in a project |
| `workflows:GetWorkflow` | Get a workflow by ID |
| `workflows:UpdateWorkflow` | Update a workflow definition |
| `workflows:DeleteWorkflow` | Delete a workflow |
| `workflows:ListWorkflowVersions` | List a workflow's archived state-machine versions |
| `workflows:GetWorkflowVersion` | Fetch one archived workflow state-machine version |
| `workflows:RestoreWorkflowVersion` | Restore an archived workflow state machine as a new version |