Permissions Reference

A permission is an action that a role allows, such as events:read. Use this page to build a role, or to find what is missing when a request is denied.

Actions do nothing on their own: put them in an IAM policy and attach it to a role that a member, team, or token has. This page lists the actions that public workflows use. The permission catalog of your environment is the final authority.

Find the necessary permission

1. Find the product area in the tables below.
2. Pick the narrowest action that does the job, such as events:read rather than events:*.
3. Put it in an allow statement with the right resource scope.
4. Attach the policy to the role of the user or team, and try the operation again.

For a denied request, keep the request ID and error code, and read Limits and failure behavior before you grant anything broader.

Every action is denied by default. A matching deny stops it, and a matching allow permits it. This applies in the Console, in CLI commands that call the control plane, and to organization-scoped tokens.

Action pattern syntax

A statement accepts three forms of action:

Pattern	Example	Meaning
One action	events:read	That action only
Namespace wildcard	events:*	Every action in the events namespace
Full wildcard	*	Every action

A resource is * or a pattern that starts with vdt:verdictan:. Roles and IAM Policies describes the statement shape and the condition operators.

Actions

Investigations and evidence

Action	Use
events:read	View governance events
events:write	Create or add events
events:export	Export governance events
escalations:read	View escalation queues
escalations:claim	Claim an escalation
escalations:resolve	Resolve an escalation
exports:read	View export jobs and download their artifacts
exports:write	Create export jobs
org:trail:read	View Trail events and evidence
org:trail:admin	Manage Trail workflows and evidence operations
ai_usage_stream:read	List AI usage stream destinations and read delivery health and delivery status
ai_usage_stream:write	Create and update AI usage stream destinations
ai_usage_stream:admin	Delete AI usage stream destinations
ai_usage_stream:ingest	Receive captured usage records. Only a gateway service token that is bound to a connected gateway holds this action.

Configurations and gateways

Action	Use
configs:read	View saved configurations
configs:write	Create or update configurations
gateways:read	View gateway status and details
gateways:register	Register a connected gateway
gateways:rotate_token	Rotate the gateway runtime token of a connected gateway
gateways:deploy	Apply gateway configuration changes
gateways:admin	Do administrative gateway mutations, such as deletion
gateways:bind_agent	Bind an agent to a gateway
gateways:unbind_agent	Remove an agent binding from a gateway
gateways:update_policy	Update a gateway policy binding
gateways:report_status	Report runtime health from a gateway runtime token
agents:manage_publication	Manage the agent publication lifecycle

Identity, teams, and policy governance

Action	Use
users:read	View organization members
users:invite	Invite members and manage invitations
users:manage	Manage member status and organization-level access
teams:read	View teams
teams:manage	Create, update, or delete teams and their members
roles:read	View roles
roles:write	Create or update roles
roles:assign	Assign roles to members or teams
policies:read	View IAM policies
policies:write	Create or update IAM policies
org:settings	Manage organization settings, with the MFA policy
org:sso	Create, test, activate, enable, and enforce SSO connections and verified domains
sso:read	View SCIM tokens
sso:write	Enable SCIM, generate or revoke SCIM tokens, and start a SCIM sync
oauth_clients:read	View registered OAuth clients
oauth_clients:write	Register or delete OAuth clients
org:audit	View organization audit activity

Tokens, spend, and notifications

Action	Use
tokens:list	List tokens
tokens:create	Create tokens
tokens:read	View token details
tokens:update	Update token metadata
tokens:rotate	Rotate token credentials
tokens:revoke	Revoke tokens
tokens:validate	Validate a token through the control-plane validation endpoint
spend:read	View spend summaries and logs
costs:read	View usage-cost summaries and provider-cost telemetry
cost_governance:write	Manage cost-governance budgets and related controls
budgets:read	View budgets
budgets:create	Create a budget
budgets:update	Update a budget
budgets:delete	Delete a budget
budgets:write	Create, update, or delete budget-policy records
notifications:read	View notifications
notifications:manage	Manage notification channels and preferences

The budgets:write action does not replace budgets:create, budgets:update, or budgets:delete.

Supporting product surfaces

Action	Use
agents:read	View agent details and supporting agent settings
agents:write	Manage access policies, usage constraints, gateway groups, and other agent settings
agents:list	List agents
agents:create	Create an agent
agents:update	Update an agent
agents:delete	Delete an eligible agent
agents:deploy	Run supported agent deployment actions
agents:bind_gateway	Add or replace agent-to-gateway links
agents:unbind_gateway	Remove an agent-to-gateway link
agents:review	Create an agent review execution
templates:read	View templates
models:read	View the published model catalog
history:read	View governed History
history:write	Manage History records when the workflow allows it
context:read	Read or resolve Context Fabric data when the context endpoint uses this action
work_receipts:read	Search user-scoped work receipts
work_receipts:write	Create user-scoped work receipts
secrets:list	List secret records when a workflow uses this action
secrets:read	View secret metadata and simulate provider-key access
secrets:write	Create, rotate, update, or delete secrets
cache:read	View Context Fabric artifacts, materialization state, and cache-governance data
cache:admin	Manage repository-source trust, artifact lifecycle actions, and cache-governance controls

Examples

A read-only evidence policy for reviewers:

verdictan iam policy create \
  --name "Evidence Reader" \
  --effect allow \
  --action events:read \
  --action exports:read \
  --action org:trail:read \
  --resource '*'

A broad identity administration policy. Review the list before you assign it:

verdictan iam policy create \
  --name "Identity Administrator" \
  --effect allow \
  --action users:read \
  --action users:invite \
  --action users:manage \
  --action teams:read \
  --action teams:manage \
  --action roles:read \
  --action roles:assign \
  --action org:sso \
  --action sso:write \
  --resource '*'

Keep these responsibilities in separate roles:

Role	Actions
Reviewer or analyst	Investigation and export actions
Configuration owner	Configuration and gateway rollout actions
Identity administrator	Invitation, team, role, and SSO actions
Finance or governance owner	Spend and budget actions
Gateway runtime token	gateways:report_status and the other gateway actions that the runtime needs

Give each credential only what its task needs. Never use an administrator token as an application token.

Limits and failure behavior

• A 403 with code auth.insufficient_permissions means that no allow matched, or a deny matched. The body does not name the action. Find the action of the route in the OpenAPI document, and simulate it with verdictan policy evaluate.
• An OAuth access token gets 403 with oauth.insufficient_scope when its approved scope does not cover the action.
• The API accepts only actions from its catalog. verdictan iam policy create fails for an unknown action.
• verdictan policy lint and verdictan policy evaluate check actions against the CLI's own list, which lacks costs:read and cost_governance:write: lint reports unsupported action pattern. Create policies with those actions in the Console or with verdictan iam policy create.
• This is a public subset. An action in the catalog is not a commitment to support an undocumented route.
• Client API tokens and gateway runtime tokens are separate from human roles. See Identity and Access.

Next steps

• Roles and IAM Policies: put actions into policies and roles.
• IAM, Members, Teams, and Roles: the CLI commands.
• Manage API Tokens: tokens with the smallest role.