Roles and permissions

How system administrators manage built-in and global roles, edit permission titles, and set platform approval rules under /admin/roles.

Overview

Admin Roles and Permissions is the platform-level RBAC surface at /admin/roles. It has three tabs:

Tab	Route	Purpose
Roles	`/admin/roles`	Built-in roles and global custom roles.
Permissions	`/admin/roles/permissions`	The permission catalog, with editable titles and descriptions.
Approval rules	`/admin/roles/approval-rules`	Platform approval floors that apply to every organization.

Detail pages live at /admin/roles/{roleId}, /admin/roles/create and /admin/roles/permissions/{permissionId}. Organization-owned roles are managed by tenant admins at /{orgSlug}/roles. See Access control.

Key concepts

Permission keys

Every permission key has the form scope.feature.action, for example system.users.manage or organization.quotes.send. The registry in code is the source of truth; the admin UI cannot add, rename or delete keys. The local catalog has 185 permissions across the system, organization and user scopes.

The system permissions are:

Key	Grants
`system.admin.access`	Access to the admin area.
`system.organizations.view`	Read organizations, including disabled ones.
`system.organizations.manage`	Edit, disable and delete organizations.
`system.billing.view`	Read subscriptions, invoices and billing state.
`system.billing.manage`	Change subscriptions, invoices and platform settings.
`system.users.view`	Read platform users.
`system.users.manage`	Invite, edit, disable, ban and delete users.
`system.audit-log.view`	Read the platform audit log.
`system.audit-log.export`	Export audit events.
`system.audit-log.reveal`	Reveal restricted audit details.
`system.analytics.view`	Read platform analytics.
`system.analytics.export`	Export platform analytics.
`system.roles.manage`	Create, edit and delete roles and permission labels.
`system.ai-models.manage`	Change AI agent policy and runtime defaults.
`system.knowledge.manage`	Manage system knowledge collections.
`system.workflows.manage`	Manage system workflows and lifecycles.
`system.approvals.manage`	Manage platform approval rules.

Built-in roles

Role	Scope	Default permissions
System Admin	System	Every system permission.
System Support	System	Admin access, organization view, billing view, user view and manage, audit log view.
Owner	Organization	Billing, delete and ownership transfer, on top of everything Admin has.
Admin	Organization	All organization permissions except the owner-only ones.
Member	Organization	View plus create and update for everyday records, without deletes.
Viewer	Organization	View permissions only.

Owner, Admin, Member and Viewer are global templates that every organization uses. Built-in roles show a lock icon. On their detail page the key, scope and permission matrix are read-only, and the role cannot be deleted. System administrators can still change the display name and description.

In tenant role pages, the four organization templates appear as locked rows that cannot be opened.

Global custom roles

A role created here has no organization, so it is global. A global role can use the system, organization, user or team scope. Tenant admins see global roles as read-only rows next to their own organization roles.

Create a role

On the Roles tab, select New role.
Enter a name. The key is generated from the name and must be lowercase with dashes.
Add an optional description and choose the Role scope.
In Permissions, select permissions individually or use Select all per group. Search and filter the matrix to find keys.
Select Create role.

Role keys must be unique.

Edit or delete a role

Open a role from the Roles tab. Save the name, description and scope in Details, and save the permission matrix separately in Permissions. Save stays disabled until something changes.

To delete a custom role, use Delete role in the danger zone or the row menu, and type the role name to confirm. Built-in roles show "Built-in system roles cannot be deleted."

Edit a permission label

The Permissions tab lists every permission with its title and scope. Open one to change its Title and Description. The key and scope are defined in application code and cannot be changed here.

Set platform approval rules

The Approval rules tab defines platform floors. They apply to every organization, and organizations can only add stricter rules on top. Without rules, risky AI actions still ask for confirmation.

Select Add rule and configure:

Name and Description.
Action and Effect, such as Customer-facing, Moves money, Destructive, Changes access, Calls an outside system or Bulk change.
Who is acting: People, AI agents, Workflows, MCP clients or API keys. Selecting none means everyone.
Only when conditions on a path, operator and value.
Requires: someone else approves, or the requester confirms.
Approvers, Approval mode (any approver, every approver or in order) and Approvals needed.
Expires after (hours), Escalate after (hours) and Escalate to.
Whether the requester may approve their own request, and whether the rule is active.

See Approvals for how requests are decided.

Permissions

Key	Effect
`system.admin.access`	Opens the admin area and these tabs.
`system.roles.manage`	Creates, edits and deletes roles and edits permission labels.
`system.approvals.manage`	Creates, edits and deletes platform approval rules.

Role writes are checked on the server and recorded in the audit log. Client-side checks only hide controls.

Overview

Admin Roles and Permissions is the platform-level RBAC surface at /admin/roles. It has three tabs:

Tab	Route	Purpose
Roles	`/admin/roles`	Built-in roles and global custom roles.
Permissions	`/admin/roles/permissions`	The permission catalog, with editable titles and descriptions.
Approval rules	`/admin/roles/approval-rules`	Platform approval floors that apply to every organization.

Key concepts

Permission keys

The system permissions are:

Key	Grants
`system.admin.access`	Access to the admin area.
`system.organizations.view`	Read organizations, including disabled ones.
`system.organizations.manage`	Edit, disable and delete organizations.
`system.billing.view`	Read subscriptions, invoices and billing state.
`system.billing.manage`	Change subscriptions, invoices and platform settings.
`system.users.view`	Read platform users.
`system.users.manage`	Invite, edit, disable, ban and delete users.
`system.audit-log.view`	Read the platform audit log.
`system.audit-log.export`	Export audit events.
`system.audit-log.reveal`	Reveal restricted audit details.
`system.analytics.view`	Read platform analytics.
`system.analytics.export`	Export platform analytics.
`system.roles.manage`	Create, edit and delete roles and permission labels.
`system.ai-models.manage`	Change AI agent policy and runtime defaults.
`system.knowledge.manage`	Manage system knowledge collections.
`system.workflows.manage`	Manage system workflows and lifecycles.
`system.approvals.manage`	Manage platform approval rules.

Built-in roles

Role	Scope	Default permissions
System Admin	System	Every system permission.
System Support	System	Admin access, organization view, billing view, user view and manage, audit log view.
Owner	Organization	Billing, delete and ownership transfer, on top of everything Admin has.
Admin	Organization	All organization permissions except the owner-only ones.
Member	Organization	View plus create and update for everyday records, without deletes.
Viewer	Organization	View permissions only.

In tenant role pages, the four organization templates appear as locked rows that cannot be opened.

Global custom roles

Create a role

On the Roles tab, select New role.
Enter a name. The key is generated from the name and must be lowercase with dashes.
Add an optional description and choose the Role scope.
In Permissions, select permissions individually or use Select all per group. Search and filter the matrix to find keys.
Select Create role.

Role keys must be unique.

Name and Description.
Action and Effect, such as Customer-facing, Moves money, Destructive, Changes access, Calls an outside system or Bulk change.
Who is acting: People, AI agents, Workflows, MCP clients or API keys. Selecting none means everyone.
Only when conditions on a path, operator and value.
Requires: someone else approves, or the requester confirms.
Approvers, Approval mode (any approver, every approver or in order) and Approvals needed.
Expires after (hours), Escalate after (hours) and Escalate to.
Whether the requester may approve their own request, and whether the rule is active.

See Approvals for how requests are decided.

Permissions

Key	Effect
`system.admin.access`	Opens the admin area and these tabs.
`system.roles.manage`	Creates, edits and deletes roles and edits permission labels.
`system.approvals.manage`	Creates, edits and deletes platform approval rules.

Role writes are checked on the server and recorded in the audit log. Client-side checks only hide controls.

Roles and permissions

Overview

Key concepts

Permission keys

Built-in roles

Global custom roles

Create a role

Edit or delete a role

Edit a permission label

Set platform approval rules

Permissions

On this page

Roles and permissions

Overview

Key concepts

Permission keys

Built-in roles

Global custom roles

Create a role

Edit or delete a role

Edit a permission label

Set platform approval rules

Permissions

On this page

Roles and permissions

OverviewCopy Anchor Link

Key conceptsCopy Anchor Link

Permission keysCopy Anchor Link

Built-in rolesCopy Anchor Link

Global custom rolesCopy Anchor Link

Create a roleCopy Anchor Link

Edit or delete a roleCopy Anchor Link

Edit a permission labelCopy Anchor Link

Set platform approval rulesCopy Anchor Link

PermissionsCopy Anchor Link

Related pagesCopy Anchor Link

On this page

Roles and permissions

OverviewCopy Anchor Link

Key conceptsCopy Anchor Link

Permission keysCopy Anchor Link

Built-in rolesCopy Anchor Link

Global custom rolesCopy Anchor Link

Create a roleCopy Anchor Link

Edit or delete a roleCopy Anchor Link

Edit a permission labelCopy Anchor Link

Set platform approval rulesCopy Anchor Link

PermissionsCopy Anchor Link

Related pagesCopy Anchor Link

On this page

Overview

Key concepts

Permission keys

Built-in roles

Global custom roles

Create a role

Edit or delete a role

Edit a permission label

Set platform approval rules

Permissions

Related pages

Overview

Key concepts

Permission keys

Built-in roles

Global custom roles

Create a role

Edit or delete a role

Edit a permission label

Set platform approval rules

Permissions

Related pages