Teams & Members

A team is Clouisle's resource isolation boundary: agents, workflows, knowledge bases, tools, and skills all belong to a team. Every in-team operation must pass two layers — a global permission code and a team membership role gate.

This page covers creating teams, adding/changing/removing members, leaving, transferring ownership, and deleting a team, plus the exact failure reason for each step. For the full role model see Roles & Permissions and the Permissions & Roles Reference.

Create a Team

1. Go to Admin → Teams.
2. Click Create Team and fill in:
   • Team Name (required, globally unique; a duplicate returns team_name_exists)
   • Description (optional)
   • Team Avatar (optional, uploaded from your machine; JPEG/PNG/GIF/WebP/SVG/ICO, recommended 200×200, max 10 MB; the upload result is stored in avatar_url)
3. Save; this calls POST /api/v1/admin/teams.
4. The creator automatically becomes the team's owner (a TeamMember row with role=owner is written too).

After creating it, select it in the team switcher. Confirm the current team when creating new agents, workflows, and knowledge bases — otherwise the resource lands in the wrong team and can only be fixed by cross-team sharing (tools only) or by recreating it.

The Two Team Surfaces

The team switcher exposes two entries with completely different permissions and capabilities:

The model authorization tab on /app/team is read-only: it shows the team's authorized models, enabled state, and today's usage/limit, and states that authorization is assigned by a system administrator. Every model-authorization write requires a superuser (see below).

Team Details and Members

Team Overview

The /app/team header shows the team avatar, name, a Default Team badge (is_default), and a badge with your role inside this team. The members tab lists username, email, role, and join date, with local filtering by username/email.

Model Authorization

Model authorization is a superuser-only capability; every write endpoint requires get_current_active_superuser:

The dashboard team detail's Model Authorization tab offers the same operations, with buttons gated on is_superuser || admin:model:update. Configurable fields include daily/monthly token limits, daily/monthly request limits, is_enabled, and priority. Granting or revoking sends a team.model_granted / team.model_revoked notification to the team. See Manage team models for details.

Add Members

1. Open the Members tab of /app/team and click Add Member (shown only when you can manage the team).
2. In the "username or email" field, enter the target user's complete username or email.
3. Pick a role: Admin, Member, or Viewer (Owner is not offered).
4. Confirm; this calls POST /api/v1/teams/{team_id}/members.

Matching rules and backend validation:

On success the new member receives a team.member_added notification and the team gets a summary notification; membership is effective immediately — there is no invitation/accept flow.

Change Member Roles

1. Find the target member in the list and open the ... menu.
2. Choose Change Role and pick Admin / Member / Viewer.
3. Save; this calls PUT /api/v1/teams/{team_id}/members/{user_id}.

Backend validation order:

On success the target receives a team.role_changed notification.

The frontend hides the menu as well: canActOnMember requires "you are not the target" and "you are the owner, or the target is not an admin". So a team admin never sees the action menu for other admins or the owner, and nobody sees it on their own row.

Remove Members

DELETE /api/v1/teams/{team_id}/members/{user_id} has two paths:

Shared limits: an owner can never be removed (cannot_remove_owner, including by themselves); if the target is not a member you get team_member_not_found (404).

After removal the user immediately loses access to all of that team's resources; only the membership row is deleted, so their conversations, API keys, and personal resources are not deleted (conversations simply become inaccessible without team access). The team receives a team.member_removed notification and so does the removed user. They can be added again later.

Leaving Teams

1. /app/team → Settings tab → danger zone, click Leave Team.
2. Confirm in the dialog; this calls POST /api/v1/teams/{team_id}/leave (requires only team:read).

After leaving you lose access to that team's resources; existing conversations are preserved. The team list refreshes and the page returns to /app.

Transfer Ownership

1. Open the member list on /app/team, find the target member, ... → Transfer Ownership (only owners see this item).
2. Confirm in the dialog; this calls POST /api/v1/teams/{team_id}/transfer-ownership?new_owner_id={user_id}.

Backend rules (in order):

1. The target must be a member of the team, otherwise team_member_not_found (404).
2. The target must already hold global team:manage, otherwise operation_not_permitted (403). Again: grant the global role first.
3. If the target is the current owner → cannot_promote_to_owner (400).
4. The previous owner's membership role is demoted to admin, the target becomes owner, and Team.owner is updated accordingly.
5. Both owners receive a team.ownership_transferred notification.

Edit Team Info

Requires the global team:update permission and owner/admin inside the team (PUT /api/v1/teams/{team_id}).

• /app/team → Settings tab: change team name, description, and avatar (inputs are disabled when you lack the permission).
• The dashboard /teams edit dialog: the same fields, requiring admin:team:update.

Fields and constraints: name is required and globally unique (duplicate → team_name_exists); description is optional; avatar_url is written by the upload component. There is no team slug, alias, or domain field.

Delete a Team

1. In the /teams list open the target team's ... menu → Delete Team (the default team does not show the item).
2. Confirm in the dialog; this calls DELETE /api/v1/admin/teams/{team_id}. The dialog only asks for confirmation — you do not type the team name.
3. The default team (is_default=true) is rejected: cannot_delete_default_team.

Deletion impact (model FK cascades, verified in models/*.py):

Team Roles and Permissions

A team role is one of four fixed values — owner / admin / member / viewer — and carries no permission codes; it only acts as the team gate. Actual capability = global role permissions ∩ team gate.

Gate Rules

• TEAM_MANAGEMENT_PERMISSIONS = team:update, team:manage, team:delete, tool:delete: these actions require both the global permission code and owner/admin in that team.
• A team viewer may only use team:read, agent:read/agent:chat, workflow:read/workflow:run/workflow:execute, kb:read/kb:test, tool:read/tool:execute, skill:read/skill:execute, conversation:read; every other write returns 403 operation_not_permitted.
• A superuser (is_superuser) bypasses membership and the team gate entirely.

Team Management Permissions

In-Team Resource Permissions

Default Team Role

The site setting default_team_id names the default team and default_team_role names the membership role new users get there. It accepts only viewer / member / admin (any other value falls back to member, which is also the default value). Assignment runs on registration and on SSO auto-provisioning, and never overwrites an existing membership. owner is never assigned automatically.

Custom Team Roles

Not implemented. Teams have exactly four fixed roles — owner, admin, member, viewer — each mapping to a fixed set of gate rules; you cannot add or remove permissions for a single team. For finer-grained permissions, use global custom roles instead (see Roles & Permissions).

Collaboration and Notifications

Collaboration happens through shared resources: agents, workflows, knowledge bases, tools, and skills are shared inside the team, and members access them subject to the role gate. Workflow run history is visible to team members (permissions permitting), so you can see who ran what and when.

Team-related automatic notifications (delivery channels are configured by administrators in site settings — see Notifications & External Channels):

Not implemented / Roadmap: there is no per-team notification configuration, and no @mentions, shared conversations, team activity feed, document comments, or in-app team messaging.

Troubleshooting

Cannot Access Team Resources

1. Confirm the correct team is selected in the team switcher.
2. Confirm you are a member of that team (if /app/team opens you are; otherwise not_team_member).
3. Confirm your global roles carry the needed code; a team viewer can only read and execute.
4. Confirm resource visibility: a private resource returns agent_access_denied / tool_access_denied to non-creators.

Cannot Change Role / No "Change Role" in the Menu

• Only the owner (or a superuser) can change roles; a team admin gets team_owner_required.
• The frontend also hides it: you cannot act on yourself, and a team admin cannot see the menu for other admins or the owner.
• An owner's role cannot be changed (cannot_change_owner_role); to change who owns the team, use Transfer Ownership.
• To promote someone to team admin, they must already hold global team:manage.

Adding a Member Returns 404 user_not_found

The input must be the complete username or complete email (email is case-insensitive). Fragments, nicknames, and display names do not match — there is no fuzzy search.

Adding a Member Returns 403 operation_not_permitted

The role was admin but the target lacks global team:manage. Grant the Team Admin global role first, then set them as team admin.

Ownership Transfer Rejected

• team_owner_required: you are not the owner (or a superuser).
• team_member_not_found: the target is not a team member; add them first.
• operation_not_permitted: the target lacks global team:manage.
• cannot_promote_to_owner: the target is already the owner.

Cannot Leave / No Leave Button

An owner cannot leave (owner_cannot_leave), and the default team hides the button in the UI. Transfer ownership first; for the default team an administrator must change the default team in site settings.

Cannot Delete a Team

• Requires admin:team:delete; the entry exists only on the dashboard /teams.
• The default team is rejected: cannot_delete_default_team.

Permissions Unchanged After a Role Change

The frontend's cached permission snapshot may be stale: refresh the page or sign in again. The backend reads permissions from the database per request, so no cache expiry wait is needed.

API Endpoints

Team endpoints use JWT user-session authentication (API keys are not accepted).

Platform side (/api/v1/teams):

Admin side (/api/v1/admin/teams):

Common Error Codes

For complete request/response formats and code examples, see Teams API.

See also:

• Roles & Permissions — global roles, team gates, and 403 troubleshooting
• User Management — user accounts and global role assignment
• Manage Team Models — model authorization and quotas