Permissions & Roles Reference

Permissions are enforced by the backend. Hiding a menu entry in the frontend is only a UX convenience; the API still returns permission errors.

Four-layer permission model

Clouisle authorization is a four-layer composite: identity bypass (is_superuser) → global capability (User → Role → Permission) → team threshold (TeamMember.role) → object layer (resource visibility and creator rules). A request fails if any layer rejects it.

Permission Catalog

Special Permissions

Permission	Description
`*`	Wildcard permission code that satisfies any permission-code check; it is itself just an ordinary code held by the Super Admin role, while the runtime "unconditional bypass" comes from `is_superuser`
`admin:dashboard:access`	Dashboard access, the key permission distinguishing "admin" from "regular user"

Dashboard Management Permissions (require `admin:dashboard:access`, granted by global roles)

Permission	Description
`admin:user:read/create/update/delete`	User management
`admin:role:read/create/update/delete`	Role management
`admin:permission:read/create/update/delete`	View and maintain permissions
`admin:model:read/create/update/delete`	Model management
`admin:memory:read`	View memory records
`admin:memory:update/delete`	Edit or delete dashboard memory records (the Admin preset holds only `admin:memory:read`)
`admin:conversation:read/delete`	Dashboard conversation management
`admin:notification:create/delete`	Dashboard notification management
`admin:team:read/create/update/delete`	System-wide team management
`admin:app:read/create/update/delete/publish/duplicate`	Agent and workflow (App) management across teams
`admin:capability:read/create/update/delete/execute`	Tool and skill (Capability) management across teams
`admin:knowledge-base:read/test/create/update/delete`	Knowledge base management from admin
`admin:settings:read`	View site settings
`admin:settings:update`	Modify site settings
`admin:integrations:login:read`	View login integrations and global SSO policy
`admin:integrations:login:update`	Manage login integrations and user SSO connections
`admin:integrations:settings:read`	View builtin email, Webhook and Feishu integrations
`admin:integrations:settings:update`	Manage builtin email, Webhook and Feishu integrations (credentials, tests, directory sync)
`audit:read`	View audit logs
`audit:export`	Export audit logs (archiving audit logs also uses this permission, independent of `admin:settings:update`)

Resource Permissions (subject to team data isolation, granted by global roles)

Permission	Description
`team:read/create/update/delete/manage`	Team management
`agent:read/create/update/delete/publish/chat`	Agent management
`workflow:read/create/update/delete/publish/run/execute`	Workflow management
`kb:read/test/create/update/delete`	Knowledge base management
`tool:read/create/update/delete/execute`	Tool management
`skill:read/create/update/delete/execute`	Skill management
`apikey:read/create/update/delete`	API Key management
`conversation:read/delete`	Conversation management
`memory:read/create/update/delete`	Team-scoped memory management

Built-in Role Matrix

The backend idempotently initializes 5 global built-in roles at startup, with the following default permissions:

Role	Type	Key Permissions	Typical Audience
Super Admin	Global built-in	Holds the wildcard code `*` and bypasses permission and team-membership checks via `is_superuser`, so it can perform system configuration, role management, audit export, and anything else	Operations lead, system owner
Admin	Global built-in	Includes `admin:dashboard:access` and almost all management permissions; excludes `admin:role:create/update/delete`, `admin:permission:create/update/delete`, `admin:settings:update`, `admin:integrations:login:update`, and `admin:memory:update/delete`	Workspace administrator, tech lead
Team Admin	Global built-in	All Member permissions plus `team:update` and `team:manage`; granted to team `owner`/`admin` members by a startup migration	Team lead, project lead
Member	Global built-in	No `admin:dashboard:access`; full collaboration permissions to create/edit/run Agents, workflows, knowledge bases, tools, and skills within a team	Developer, solution builder
Viewer	Global built-in	Read-only role: view/chat/run published Agents and workflows and read/execute tools and skills within a team (no `apikey:*`)	Auditor, observer

Team Member Roles and Team Scope

Team member roles (owner, admin, member, viewer) are only organizational level labels inside a team and do not by themselves constitute role authorization. The authorization chain is entirely global-permission based:

PermissionChecker checks whether the user's global roles contain the target permission code (* counts as everything; is_superuser bypasses outright).
When a resource carries a team_id, TeamMember membership is checked; management actions require TeamMember.role in (owner, admin), and a team viewer is limited to the read/use allowlist.

Team-scoped RBAC is retired

The historical design's ScopedRoleAssignment (team-scoped roles) and check_scoped_permission are retired: the ScopedRoleAssignment model is still defined and exported in code, but nothing creates or reads it. The startup migration migrate_team_admin_roles() explicitly grants the global Team Admin role to members whose TeamMember.role in (owner, admin) and deletes leftover team-scoped assignments. Team management capability therefore comes from the global Team Admin role, not from a team member scope.

Team management boundaries (team_access.py):

TEAM_MANAGEMENT_PERMISSIONS = team:update, team:manage, team:delete, tool:delete: these actions require both the global permission code and an owner/admin role in the target team.
VIEWER_ALLOWED_PERMISSIONS: a team viewer may only perform team:read, agent:read/agent:chat, workflow:read/workflow:run/workflow:execute, kb:read/kb:test, tool:read/tool:execute, skill:read/skill:execute, and conversation:read; all other writes are denied.
A team viewer is not the same as the global Viewer role: team viewer only means the lowest management level inside that team and does not automatically grant the global Viewer permission codes.
Adding a member, changing a member role, removing a member, leaving a team, and transferring ownership only maintain TeamMember.role; they never grant or revoke any global role. owner is never assigned automatically as a default team role.

Menu Item	Required Permission	Super Admin	Admin	Member
Dashboard	`admin:dashboard:access`	✓	✓
Teams	`admin:team:read`	✓	✓
Knowledge Bases	`admin:knowledge-base:read`	✓	✓
Activities	`admin:conversation:read` + `workflow:read` (both required)	✓	✓
Users	`admin:user:read`	✓	✓
Roles	`admin:role:read`	✓	✓
Permissions	`admin:permission:read`	✓	✓
API Keys	`apikey:read`	✓	✓	✓
Models	`admin:model:read`	✓	✓
Apps	`admin:app:read`	✓	✓
Capabilities	`admin:capability:read`	✓	✓
Memories	`admin:memory:read`	✓	✓
Observability	`admin:dashboard:access`	✓	✓
Notifications	`admin:dashboard:access`	✓	✓
Audit Logs	`audit:read`	✓	✓
Site Settings	`admin:settings:read`	✓	✓

The sidebar renders five groups: General (Dashboard, Teams, Knowledge Bases, Activities), System (Users, Roles, Permissions), Resources (Models, Apps, Capabilities, API Keys, Memories), Monitoring (Observability, Notifications, Audit Logs), and Settings (Site Settings, Help Center).

System, Resources, and Monitoring are gated as a whole on admin:dashboard:access: without it the entire group is hidden.
General and Settings are not hidden as a group by admin:dashboard:access, but each item still requires its own permission (for example, a user with only admin:team:read sees Teams and Activities but not Dashboard). The Help Center external link requires no permission.
Route permission mapping lives in frontend/lib/route-permissions.ts: /apps and /capabilities use prefix matching; there is no /tools route (tool/skill management lives under /capabilities); /site-settings/integrations uses either admin:integrations:login:read or admin:integrations:settings:read; the Storage page's "archive audit logs" action uses audit:export on its own.

Check Order

A superuser (is_superuser) passes PermissionChecker outright without checking role permissions and typically also skips team-membership checks. An ordinary user goes through, in order:

Global permission: whether User → Role → Permission contains the target permission code (* counts as everything).
Team threshold: when the resource belongs to a team, the user must be a member; management actions additionally require owner/admin, and a team viewer is bound by the read/use allowlist.
Object visibility: private resources must additionally pass the creator rule.

A request fails when the resource does not belong to the current team, the user is not a member, the user is inactive, or the API key does not list the target resource.

Role Restrictions

System roles (is_system_role) and system permissions (is_system) cannot be deleted; the default team, owners, and superusers have additional protections. Transferring ownership, removing an owner, and modifying system permissions are explicitly rejected (error codes 5200–5214).