Roles & Permissions

Authorization in Clouisle stacks global roles and team gates. The frontend hides menus and buttons by permission, and the backend re-validates in API dependencies — "cannot see the entry point" is not a security boundary; the endpoint still returns 403.

For the full permission catalog and built-in role matrix, see the Permissions & Roles Reference. This page covers how to operate it, who has which permission, and what happens when it fails.

Permission Model

Permission Hierarchy

Identity layer (is_superuser bypasses everything; no permission or membership check)
  └── Global layer (User → Role → Permission, matched by permission code; `*` matches anything)

Global-layer namespaces
  ├── Admin permissions (admin:*, requires admin:dashboard:access to enter the dashboard)
  │     ├── admin:user:*, admin:role:*, admin:permission:*
  │     ├── admin:team:*, admin:model:*, admin:app:*, admin:capability:*
  │     ├── admin:knowledge-base:*, admin:settings:*, admin:sso:*
  │     ├── admin:conversation:*, admin:memory:*, admin:notification:*
  │     └── audit:read, audit:export
  └── Resource permissions (team:*, agent:*, workflow:*, kb:*, tool:*, skill:*, apikey:*, conversation:*, memory:*)

Team gate layer (TeamMember.role: owner / admin / member / viewer)
  └── Applied when the resource carries team_id: the user must be a member; owner/admin-only
      operations are decided by TEAM_MANAGEMENT_PERMISSIONS

The two layers are an AND: the global layer supplies "what may be done", the team gate supplies "in which team and at what level". Team roles therefore grant no permission codes themselves, and admin-dashboard permissions can never come from a team role.

Permission Check Order

For a team-scoped request the backend runs, in order (see backend/app/api/team_access.py):

1. Team exists: missing team → team_not_found, HTTP 404.
2. Superuser shortcut: is_superuser=True passes immediately, without role or membership checks.
3. Membership: not a member of that team → not_team_member, HTTP 403.
4. Team admin gate: when the required permission is in TEAM_MANAGEMENT_PERMISSIONS (or the caller explicitly requires it) and the membership role is not owner/admin → team_admin_required, HTTP 403.
5. Team viewer limit: membership role is viewer and the required permission is not in VIEWER_ALLOWED_PERMISSIONS → operation_not_permitted, HTTP 403.
6. Global permission code: some global role of the user must contain the code (or the wildcard *); otherwise operation_not_permitted, HTTP 403.

Permission Types

Dashboard / Admin permissions (admin: and audit: prefixes):

Resource permissions (constrained by team data isolation):

Built-in Roles

At startup the backend idempotently initializes 5 global built-in roles (is_system_role = true) from SystemPermissions. They cannot be renamed or deleted, and their permission sets cannot be changed through the API.

Super Admin

Name: Super Admin
Type: System built-in
is_superuser: true  # the account also carries the superuser flag
Permissions:
  - "*"           # wildcard code, matches any permission check

The first user registered in the system is automatically promoted to Super Admin and assigned this role. An is_superuser=True account passes team endpoints directly, but it still needs a TeamMember row to appear in member lists such as /teams/my.

Admin

Name: Admin
Type: System built-in
Permissions:
  # Admin dashboard
  - admin:dashboard:access
  - admin:user:read/create/update/delete
  - admin:role:read            # read-only: cannot create/edit/delete roles
  - admin:permission:read      # read-only: cannot create/edit/delete permissions
  - admin:team:read/create/update/delete
  - admin:model:read/create/update/delete
  - admin:capability:read/create/update/delete/execute
  - admin:app:read/create/update/delete/publish/duplicate
  - admin:knowledge-base:read/test/create/update/delete
  - admin:settings:read
  - admin:sso:read
  - audit:read/export
  - admin:conversation:read/delete
  - admin:notification:create/delete
  - admin:memory:read
  # Team-scoped resource permissions (explicit codes, no wildcard)
  - team:read/create/update/delete/manage
  - agent:read/create/update/delete/publish/chat
  - workflow:read/create/update/delete/publish/run/execute
  - kb:read/test/create/update/delete
  - tool:read/create/update/delete/execute
  - skill:read/create/update/delete/execute
  - apikey:read/create/update/delete
  - conversation:read/delete

Admin can manage every team and its members (team:manage), but team-management actions still require them to be owner/admin inside that team.

Team Admin

Name: Team Admin
Type: System built-in
Permissions: all Member permissions, plus
  - team:update    # change team name/description/avatar
  - team:manage    # add/change/remove members

The startup migration migrate_team_admin_roles() grants this role to every user whose membership role is owner or admin in at least one team, and cleans up legacy team-scoped assignments. Consequently, before making someone a team admin they must already hold the global team:manage (usually by being given the Team Admin role first), otherwise the endpoint returns 403.

Member

Name: Member
Type: System built-in
Permissions:
  - team:read
  - agent:read/create/update/chat        # no delete / publish
  - workflow:read/create/update/run      # no delete / publish / execute
  - kb:read/test/create/update/delete
  - tool:read/create/update/delete/execute
  - skill:read/create/update/delete/execute
  - apikey:read/create/update/delete
  - conversation:read/delete

Note: Member holds tool:delete, but tool deletion requires team owner/admin (tool:delete belongs to TEAM_MANAGEMENT_PERMISSIONS), so a Member cannot actually delete team tools.

Viewer

Name: Viewer
Type: System built-in
Permissions:
  - team:read
  - agent:read/chat
  - workflow:read/run
  - kb:read/test
  - tool:read/execute
  - skill:read/execute
  - conversation:read

Viewer is the only default role: first initialization points the site setting default_role_id at Viewer, so newly registered users (including SSO-provisioned ones) get it by default.

The Two UI Surfaces

Two interfaces deal with teams and roles, and their permission requirements differ:

Members and Viewers cannot see /teams (the frontend blocks on admin:team:read and the admin endpoints validate admin:team:*), so their only team entry is /app/team. The model tab on /app/team is read-only: it shows the team's authorized models and today's usage, stating that authorization is assigned by a system administrator.

Role Management

The dashboard Roles page (/roles) lists every role. That route requires admin:role:read — the built-in Admin role only has read, so only a Super Admin (or a custom role carrying admin:role:*) can create, modify, or delete custom roles.

Create a Custom Role

1. Sign in as Super Admin and go to Admin → Roles.
2. Click Create Role and fill in Name (globally unique) and Description.
3. Check permission codes in the list (you can select all within a category).
4. Save. POST /api/v1/admin/roles requires admin:role:create.

Custom roles are global roles (is_system_role = false) and can be assigned as any user's global role, independent of team membership. A duplicate name returns role_with_name_exists.

Example:

Name: Content Manager
Description: Manages knowledge bases and documents, no dashboard access
Permissions:
  - team:read
  - kb:read/test/create/update/delete
  - agent:read/chat

Edit a Role

PUT /api/v1/admin/roles/{role_id} changes the name and description (admin:role:update); PUT /api/v1/admin/roles/{role_id}/permissions takes { "permissions": [...] } and replaces the whole set (not incremental). Both reject system roles:

• name/description → cannot_modify_system_role
• permission set → cannot_modify_system_role_permissions

Delete a Role

DELETE /api/v1/admin/roles/{role_id} requires admin:role:delete. Two hard limits:

• System role → cannot_delete_system_role
• Still assigned to users → role_in_use, with count in the error payload

Custom Permissions

The permission catalog itself is maintainable (/permissions page, requires admin:permission:read):

System permissions (is_system=true, i.e. every code defined in SystemPermissions) cannot be modified or deleted: cannot_update_system_permission / cannot_delete_system_permission. A duplicate custom code returns permission_with_code_exists.

User Permissions

View User Permissions

Admin → Users opens the user list (requires admin:user:read). The user detail/edit panel shows:

• The user's global roles (multi-select, the roles field)
• Team memberships and in-team roles (maintained from the teams pages)
• SSO connections, auth_source, is_active, and the is_superuser flag

There is no aggregate "effective permissions" view: actual permissions are the union of permission codes from all global roles plus the team gates, so you compare manually against the Permissions Reference.

Change a User's Global Roles

1. In Admin → Users, click Edit on the target user.
2. Check/uncheck roles in the Role area (multi-select).
3. Save. The frontend calls PUT /api/v1/admin/users/{user_id} with roles: ["Admin", ...], requiring admin:user:update.

Backend behaviour:

• roles replaces the set: it clears first and then writes, so roles you omit are lost.
• Role names must match exactly; unmatched names are ignored.
• Protection rule: if the user is still owner/admin of some team and the new role set no longer contains team:manage (or *), the request fails with 403 operation_not_permitted (permission: team:manage). To strip a team administrator, first downgrade their membership role in every team.

Grant Special Permissions

Not implemented / Roadmap. There is no per-user permission grant/revoke with scope and expiry. The endpoints GET /users/{user_id}/permissions, /permissions/check, and POST/DELETE /users/{user_id}/permissions do not exist. Permissions are assigned only through global roles (PUT /api/v1/admin/roles/{role_id}/permissions) and team memberships.

Team Permissions

Team Roles Are Gates, Not Grants

TeamMember.role has exactly 4 fixed values: owner, admin, member, viewer. It carries no permission codes; it answers only two questions: is this person a member of this team, and is their level high enough for a management action.

The legacy ScopedRoleAssignment (team-scoped role table) and check_scoped_permission design is retired: the model is still defined in code, but nothing creates or reads it, and the startup migration only deletes leftover rows. Team management capability therefore comes from the global Team Admin role, not from a team-scoped grant.

Two rules:

A team viewer and the global Viewer role are two different things: the former only means "lowest level inside this team" and grants no global Viewer codes; conversely, when adding a global Viewer to a team, use the viewer membership role.

Typical Team Role Combinations

Real capability = global role permissions ∩ team gate. The most common combinations (assuming the member already holds the matching global role):

Full constraints on team-management actions live in Teams & Members.

Resource Visibility

Beyond the two gates, the resource's own visibility also blocks access:

Agent example:

Agent: Customer Support Agent
Owner: john.doe@example.com
Team: Support Team

Access control:
  visibility=team  → team members can read; writes need the owner or a team owner/admin
  visibility=private → only the creator (or team owner/admin when the creator is absent)
Team members: Read, Chat
Other teams: No access

Workflow example:

Workflow: Customer Inquiry Processing
Owner: jane.smith@example.com
Team: Support Team

Access control:
  visibility=team  → team members can read; writes need the owner or a team owner/admin
  visibility=private → only the creator (or team owner/admin when the creator is absent)
Team members: Read, Run
Other teams: No access

Share Resources

Cross-team sharing exists only for tools:

• Custom tools can be shared with other teams via POST /api/v1/admin/tools/{tool_id}/share (list with GET /api/v1/tools/{tool_id}/shares, unshare with DELETE /api/v1/tools/{tool_id}/share/{team_id}).
• Agents / workflows / knowledge bases have no per-team sharing level: cross-team visibility comes from the resource's visibility (Team / Public for agents), and access is otherwise team-isolated.

API Key Scopes

An API key carries a scopes list (default ["chat"]; an empty list means unrestricted), a rate_limit (requests per minute, 0 = unlimited), an expires_at, and can be bound to specific agents and workflows. Keys are managed on the /api-keys page or /app/api-keys, created via POST /api/v1/api-keys (requires apikey:create).

API Key: ak_...
Owner: integration@example.com
Scopes:
  - chat
Rate limit: 1000 (requests/minute)
Expires at: 2027-02-11

Permission Auditing

View Permission Changes

Not implemented / Roadmap. There is no dedicated permission-change audit view, and the audit log has no granted / revoked action types.

Current audit coverage (each endpoint checked):

Review entries in Audit Logs (requires audit:read), filtered by resource and operation. See Audit Logs.

Permission Usage Reports

Not implemented / Roadmap. There are no per-user/team permission usage reports, unused-permission lists, or over-privilege detection.

Troubleshooting 403s

Permission Denied

Symptoms: a feature is unavailable, or the API returns 403 operation_not_permitted / team_admin_required / not_team_member.

Check in order:

1. Is the global permission code missing? Go to Admin → Users → edit the user and check whether roles includes a role carrying the target code (compare with the Permissions Reference). The error response carries a permission field naming the missing code.
2. Is the team gate the wrong level? When the action uses a management permission (team:update/team:manage/team:delete/tool:delete) the user must be team owner/admin; a team viewer is always rejected for writes.
3. Is the user not a member? not_team_member (403) means the user is not in that team at all.
4. Is it resource visibility? A visibility=private resource returns agent_access_denied / tool_access_denied (403) to non-creators, regardless of role permissions.
5. Is it API key ownership? A key can only be read/written by its owner or a superuser; anyone else gets permission_denied.

Over-Privileged Users

1. In Users, check the target user's roles and compare each against the Permissions Reference.
2. In Roles, review each role's permission set — note that the built-in Admin role already covers all team resources, so stacking extra broad custom roles is usually unnecessary.
3. Before downgrading, verify whether the user is still owner/admin of any team; otherwise PUT /admin/users/{id} is rejected by the team:manage protection rule.
4. Review regularly. User and team-membership changes are audited, but role create/update/delete is not, so keep your own record of role edits.

Inconsistent Permission Behaviour

1. Identify the layer: a team-scoped request is "global code + team gate"; only dashboard endpoints look at admin:*.
2. Identify the source: users may hold several roles and permissions are unioned; the startup migration may also have added Team Admin.
3. Remember system roles cannot be hand-edited: their permission sets are re-synced to the code list on every start, so direct database edits do nothing.

Best Practices

✅ Do:

• Carry job permissions in custom roles instead of adding more built-in roles
• Grant the Team Admin global role first, then set the person as team admin (the reverse order is blocked with 403)
• Use team viewer + global Viewer together for read-only team members
• Create and rotate API keys per integration instead of sharing a personal account's key
• Review role members and team owner/admin lists quarterly
• Validate permission changes in a test environment before production

❌ Don't:

• Hand out * (only Super Admin should hold it)
• Try to stack permissions onto the built-in Admin role (it does not work; the startup sync reverts it)
• Treat "the frontend hides the button" as a security boundary
• Run several integrations from one shared account

API Access

Role and permission endpoints live under /api/v1/admin/roles and /api/v1/admin/permissions and require admin:role:* / admin:permission:*:

# List roles (page / page_size / search)
roles = api.get("/api/v1/admin/roles")

# Create a role
role = api.post("/api/v1/admin/roles", json={
    "name": "Content Manager",
    "description": "Manages knowledge bases",
    "permissions": ["team:read", "kb:read", "kb:create", "kb:update", "kb:delete", "kb:test"],
})

# Replace a role's permissions wholesale (PUT, not PATCH)
api.put(f"/api/v1/admin/roles/{role_id}/permissions", json={
    "permissions": ["kb:read", "kb:create"],
})

# List permissions, optionally filtered by scope
permissions = api.get("/api/v1/admin/permissions", params={"scope": ["admin", "team"]})
scopes = api.get("/api/v1/admin/permissions/scopes")

Note: There are no per-user permission endpoints (/users/{user_id}/permissions); user permissions can only be replaced wholesale through the roles field.

Protection Rules

• System roles (the 5 built-in roles) and system permissions cannot be deleted or renamed, and their permission sets cannot be changed (the startup sync restores the code list).
• A custom role must be unassigned before deletion, otherwise role_in_use.
• Superuser accounts cannot be deleted (cannot_delete_superuser) or deactivated (cannot_deactivate_superuser).
• The default team cannot be deleted (cannot_delete_default_team); a team owner cannot leave or be removed — transfer ownership first.
• Permission changes apply to subsequent requests immediately; issued JWTs are not a permission cache.

Related Documentation

• Permissions & Roles Reference — the full permission catalog, built-in role matrix, and sidebar mapping
• Teams & Members — adding/changing/removing members, leaving, transferring ownership, and the team API
• User Management — creating, activating/deactivating, deleting users, and assigning roles
• Audit Logs — audit records of role and membership changes