Permissions Reference
Keeptrusts uses scoped permissions to control what a person or token can do inside an organization. This page focuses on the organization-scoped actions used by the customer workflows documented on this site. The permission catalog shown when creating or editing a role is authoritative for the active environment; internal, platform-admin, and reserved action strings can also exist in the API action registry.
How permission checks work
Keeptrusts evaluates access with deny-by-default behavior:
- A matching deny wins.
- A matching allow grants access.
- If nothing allows the action, the request is denied.
That model applies to console workflows, CLI commands that call the control plane, and organization-scoped tokens.
Public action groups
Investigations and evidence
| Action | Purpose |
|---|---|
events:read | View governance events |
events:write | Create or ingest 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 |
exports:download | Reserved action string; current artifact download handlers check exports:read |
org:trail:read | View Trail events and evidence |
org:trail:admin | Administer Trail workflows and evidence operations |
Configurations and gateways
| Action | Purpose |
|---|---|
configs:read | View saved configurations |
configs:write | Create or update configurations |
gateways:read | View gateway status and details |
gateways:write | Reserved action string; current gateway mutations use the granular actions below |
gateways:register | Register a connected gateway |
gateways:rotate_token | Rotate a connected gateway's machine token |
gateways:deploy | Apply gateway configuration changes |
gateways:admin | Perform 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's policy binding |
gateways:report_status | Report runtime health from machine credentials |
agents:manage_publication | Manage agent publication lifecycle |
Teams, users, and policy governance
| Action | Purpose |
|---|---|
users:read | View organization members |
users:invite | Invite members |
users:manage | Manage member status and org-level access |
teams:read | View teams |
teams:manage | Create, update, or delete teams |
roles:read | View roles |
roles:write | Create or update roles |
roles:assign | Assign roles to users or teams |
policies:read | View IAM policies |
policies:write | Create or update IAM policies |
org:settings | Manage organization settings |
org:sso | Manage the legacy organization SSO settings routes |
sso:read | View current SSO connections, verified domains, and SCIM configuration |
sso:write | Create or manage current SSO connections, domains, mappings, and SCIM credentials |
oauth_clients:read | View registered OAuth clients |
oauth_clients:write | Register, update, or deactivate OAuth clients |
org:audit | View organization audit activity |
Tokens, spend, and notifications
| Action | Purpose |
|---|---|
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 |
tokens:use_gateway | Reserved action string; no current API handler checks it as the gateway-use authorization boundary |
spend:read | View spend summaries and logs |
org:billing | Broad organization billing permission accepted by legacy and current billing, payment, subscription, and wallet routes |
billing:view | View bills, invoices, balances, and billing summaries where the selected endpoint accepts it |
billing:export | Export billing records |
billing:configure | Manage billing configuration and supported administrative bill operations |
billing:share | Create or revoke shared billing links |
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; this does not replace the granular budget create, update, and delete actions above |
notifications:read | View notifications |
notifications:manage | Manage notification channels and preferences |
Supporting product surfaces
| Action | Purpose |
|---|---|
agents:read | View agent details and supporting agent settings |
agents:write | Manage supporting agent settings such as access policies, usage constraints, and gateway groups |
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 |
agents:admin | Perform agent publication administration where the endpoint accepts this fallback |
templates:read | View templates |
templates:write | Reserved action string; no current customer template create/update handler checks it |
models:read | View the published model catalog |
history:read | View governed history |
history:write | Create, update, share, remove, recall, or condense history records where the workflow permits it |
history:learn | Reserved action string; current recall and condensation handlers check history:write instead |
context:read | Read or resolve Context Fabric data where the context endpoint checks this action |
work_receipts:read | Search user-scoped work receipts |
work_receipts:write | Create user-scoped work receipts |
secrets:list | List secret records where a workflow checks the list action |
secrets:read | View secret metadata and simulate provider-key access |
secrets:write | Create, rotate, update, or delete secrets |
cache:read | List and inspect cache-warmer definitions and related cache-governance state |
cache:admin | Create and manage cache-warmer definitions |
Typical role design
A practical organization setup usually separates these concerns:
- Reviewers and analysts need investigation and export permissions.
- Configuration owners need config and gateway rollout permissions.
- Identity administrators need invite, team, role, and SSO permissions.
- Finance or governance owners need spend and budget visibility.
- Machine credentials should be narrower than human admin roles.
Token guidance
Use separate credentials for separate jobs:
- Request-execution tokens for applications sending governed traffic
- Runtime tokens for gateways reporting state or connecting to managed workflows
- Human user roles for console and CLI operations that require broader review or rollout access