---
title: Teams, subteams and roles
description: How Venom Cloud models an org's teams, subteams, members and roles once for every product, what an org role allows in each product, and how today's Tasks teams and Notes team vaults fit in.
section: cloud
order: 12
audience: [user, agent, builder]
sources: [services/nodejs-cloud/lib/org/teams.ts, services/nodejs-cloud/lib/org/mcp.ts, services/nodejs-cloud/app/(console)/(shell)/settings/org-teams/page.tsx, services/nodejs-cloud/components/org/TeamPicker.tsx, services/nodejs-cloud/lib/org/member-ref.ts, services/nodejs-cloud/lib/org/members.ts, services/nodejs-cloud/migrations/0213_org_teams.sql, services/nodejs-cloud/contracts/org-teams.ts, services/nodejs-cloud/contracts/org-teams-v1.schema.json, services/nodejs-cloud/components/console/rbac.ts, services/nodejs-cloud/lib/people/auth.ts, services/nodejs-cloud/lib/calendar/auth.ts, services/nodejs-cloud/lib/chat/auth.ts, services/nodejs-cloud/lib/support/auth.ts, docs/adr/0077-org-teams.md, services/nodejs-cloud/migrations/0216_scim_team_sync.sql, services/nodejs-cloud/lib/scim/teams.ts, services/nodejs-cloud/components/sso/ScimGroups.tsx]
features: [cloud.migrations, cloud.console-settings]
---

An org has teams. A team can have subteams, to any depth. People and agents are members of a team with a role. The
same teams are meant to be used by every product: "Engineering" in Tasks is the same team as in Notes, People and
Calendar, with the same members.

You manage them in one place, **Settings → Teams** in the console. The products move onto the model one at a time;
[What changes when](#what-changes-when) lists the order.

## Teams and subteams

- A team has a name, a key and an optional description. The key is a short code, unique in the org, such as `ENG`.
  Tasks uses it as the issue prefix (`ENG-123`). A team made without a key gets one from its name.
- A team can sit under another team, up to 8 levels deep (a top-level team is level 1). A team cannot be moved under
  itself or under one of its own subteams. The database refuses both (migration 0312).
- A team can be archived. Archived teams keep their members and history and are hidden from team lists. A team whose
  subteams aren't all archived can't be archived (archive or move them first), and nothing is made or moved under an
  archived team.
- When a team is deleted, its subteams move up to its parent; they are never deleted with it.
- A team can be **private**. By default it is not, and everyone in the org can see the team and its content. A private
  team's content is visible only to its members and to org owners and admins. The team's name still shows in lists for
  members of its subteams.

## Members and team roles

A member is a person (`user:<id>`) or an agent (`agent:<id>`). Each has one of two team roles:

| Team role | What they can do |
|---|---|
| **admin** | Manage the team: rename it, change its key, add and remove members, change roles, make and move subteams under it |
| **member** | Be in the team: see its content and work in it, in every product that uses teams |

Venom Tasks used to call the admin role `lead`; a lead is an admin now.

**Membership flows down.** A member of a team is also a member of every subteam under it, with the same role. So an
admin of Engineering manages Platform and Databases under it, and a member of Engineering sees a private Databases
team. It does not flow up: a member of Databases is not a member of Engineering.

**A team keeps an admin.** Once a team has an admin, the last one cannot be removed or made a member: make someone else
an admin first. Org owners and admins can manage every team, including ones with no admin (teams copied from Tasks
often have none).

Anyone can leave a team on their own, except a team that syncs from your identity provider.

## Teams from your identity provider

If your org provisions members with SCIM ([Single sign-on](/docs/cloud/console-sso.md)), a group from your identity provider can
sync into a team. Open **Settings → Single sign-on**. Under SCIM provisioning, **Groups** lists every group your IdP
has pushed, with its people, the org role its group rule gives, and the team it syncs into. Pick a team for a group, or
**New team named "…"** to make one, and save. Only owners can change this.

- The team's people become the group's active members at once. Anyone in the team who is not in the group leaves,
  admins too. Agents in the team stay.
- From then on the team follows the group. Adding someone to the group in your IdP adds them to the team. Removing
  them, deactivating them or deleting them takes them out. Reactivating them puts them back.
- Nobody can add, remove or change the role of a person in a synced team by hand, in any product, the API or MCP.
  They get this message: *This team's members come from your identity provider (the group "Engineering"). Change the
  group there, or unlink it in Settings → Single sign-on.* Leaving the team is refused the same way.
- Everyone in a synced team is a member, so org owners and admins manage it. Its name, key, description, privacy,
  subteams and archive state can still be changed as usual.
- A team follows one group at a time. Picking **Not synced** (or deleting the group in your IdP) stops the sync: the
  team keeps its people, and people can edit it again.

A group still gives its people an org role through the group rules in Provisioning. The role and the team are set
separately: a group can do either, both or neither.

## Managed service staff

Staff of a [managed service](/docs/cloud/console-msp.md) that works in your org can be added to your teams, though they are not
members of your org. They are `user:<id>` like anyone else, and team lists show the managed service's name next to
them as a badge (`msp` in the API).

They join a team as members. They can be a team's admin only if your org allows it: an owner turns on **Their staff
may be team admins** in **Settings → Managed services → Change access**. Turning it off makes any of them who are
team admins members again. When a staffer's access ends (you remove them or revoke the service, or the service ends the
link), they leave every team.

## Settings → Teams {#settings}

Open **Settings → Teams** (`/settings/org-teams`). Every member of the org can open it and see the teams that are
not private, plus the private teams they are in.

- **The tree.** All teams, with their subteams under them. Search by name, key or description; tick **Show archived**
  to see archived teams. Pick a team to open it on the right (under the tree on a phone).
- **New team.** Org owners and admins make top-level teams; a team's admins make subteams under it (**Subteam** on the
  team, or **New team** with a parent picked). You become the new team's first admin.
- **Edit.** Rename the team, change its description or its key. A Tasks team's key is its issue prefix: its issues
  take the new key, and links and identifiers with the old one keep working.
- **Move.** Drag a team onto another team to put it under that team, or onto **Drop here for the top level**. On a
  phone, or if you prefer, use **Move to…** and pick the new parent. A team cannot move under itself or one of its own
  subteams; those rows are greyed out.
- **Private.** The switch on the team. Only its members (and org owners and admins) see its content.
- **Archive.** Hides the team from pickers and lists, keeps its members and subteams. **Restore** brings it back. A
  team that is also a Tasks team is retired in Tasks too.
- **Members.** Add a person or an agent with a role, change a role, remove someone. Members who come from a team above
  are shown greyed with "from" and that team's name; manage them on that team. Anyone can leave a team with the × on their own row. A team that syncs from your
  identity provider refuses member changes here (see [Teams from your identity provider](#teams-from-your-identity-provider)).

Org owners and admins manage every team. A team's admins manage that team and its subteams. Everyone else sees the
page read-only.

## Org roles and products

Your org role (owner, admin, developer, billing or viewer, set in [Members and roles](/docs/cloud/console-orgs-members.md)) means
the same thing in every product. The levels are:

- **manage**: the product's settings and everyone's content in it
- **write**: create and change your own work
- **read**: see what you have access to
- **none**: the product is not open to you

<!-- product-access:start -->
| Product | owner | admin | developer | billing | viewer |
|---|---|---|---|---|---|
| Tasks | manage | manage | write | read | read |
| Notes | manage | manage | write | write | write |
| People | manage | manage | write | read, own: write | read, own: write |
| Funnel | manage | manage | write | write | write |
| Outreach | manage | manage | write | write | write |
| Calendar | manage | manage | write | read, own: write | read, own: write |
| Incidents | manage | manage | write | read | read |
| Chat | manage | manage | write | read | read |
| Support | manage | manage | write | read | read |
| Forms | manage | manage | write | read | read |
| Comms | manage | manage | write | read | read |
| Flags and Experiments | manage | manage | write | read | read |
| Computers | manage | manage | write | read | read |
| Agents | manage | manage | write | read | read |
| Studio | manage | manage | write | read | read |
| Billing | manage | read | none | manage | none |
<!-- product-access:end -->

"own: write" means every member keeps writing their own personal things, whatever their role: in People, their own
private contacts; in Calendar, their own availability, schedules, booking page and bookings.

This table is generated from the code, and every product's permission checks read it: the app, a member's personal API
key and an app connected with OAuth. A check in the test suite fails if the table here drifts from the code.

What each level means in the products where it is not obvious:

| Product | write | manage |
|---|---|---|
| People | Share a contact with a team or the org, change a shared contact, change a company's details | Connect the org's Telegram bot |
| Calendar | Create, change and delete event types and set their team hosts | The org's own Google and Microsoft sign-in apps |
| Chat | Post | Moderate any channel |
| Comms | Send messages and calls | Senders, mailboxes, routes and Venom Line settings |
| Tasks | Create and change issues | Teams, workflows and agents |

### What can narrow it further

- **An app connected with OAuth** gets at most what its scopes say, and never more than your role. A `people:write`
  scope does not let a viewer share contacts. One exception for now: in Comms, an app with `comms:write` can ask to
  send whatever your role (an agent's message still waits for a person's approval).
- **A read-only API key** reads, whatever the role of the member it belongs to.
- **A partner (MSP) session** gets at most what the client's grant allows: without scopes it reads; the API keys scope
  lets it write; the settings scope lets it manage. It never gets more than the role it was given.
- **A team API key** (one that belongs to no member) is an agent, not a person. It keeps the rights each product gives
  agents, which this table does not change.

### What changed in November 2026

Before, each product had its own rules. These changed when the products moved onto the table:

| Product | Role | Before | Now |
|---|---|---|---|
| Chat | billing | Post | Read only |
| Calendar | billing, viewer | Event types, team hosts, own availability and bookings | Own availability, schedules and bookings; event types and team hosts are read only |
| Calendar | developer | manage | write (nothing changes in use: the org's own sign-in apps were already owners' and admins') |
| People | billing, viewer | Change any contact they own, shared or not, and companies | Own private contacts only: sharing a contact, changing a shared one and changing a company are refused |
| People, Funnel | owner, admin | write | manage (People: the org's Telegram bot, as before) |
| Forms | owner, admin | write | manage (Forms has no separate admin rights, so nothing changes in use) |
| Comms | developer | Read only | Send messages and calls (changing the settings still needs owner or admin) |
| Tasks | all | Write followed the `keys:write` permission | Write follows the table (the same roles: owner, admin, developer) |

Partner (MSP) sessions are now held to the client's grant in every product. Before, Tasks, Comms and Outreach applied
it, while Chat, Support, People, Calendar, Incidents, Forms and Flags gave a partner's staff everything their role
allowed.

Billing and viewer members keep writing in Notes, Funnel and Outreach, as before (the table says `write`). The design
in ADR 0077 has them read only there; that is the owner's call and has not been made.

## Mesh teams are key groups

The console's **Settings → Tenants & key groups** page holds API keys, join tokens, daemons, policies and GPU grants.
Those **key groups** have no people in them and are not the teams on this page. The console, the docs and the CLI call
them key groups. The API and the database keep the old names (`team`, `team_id`, `/admin/v1/teams`), so a `team_id` on
an API key, daemon or policy is a key group's id. "Team" in Venom now means only the teams on this page.

## Teams as targets {#targets}

Wherever a product asks for a list of people, it can take a team instead and follow it as people join and leave.
Members are MemberRefs, and inherited members count.

| Product | What a team does | How it follows the team |
|---|---|---|
| [On-call](/docs/incidents/on-call) | A rotation of "members of team X", in the order they joined (newcomers last). A team as an escalation target pages its current on-call. Paging still needs each person's verified phone; anyone without one is skipped, with a note | Read each time a shift or a page is worked out |
| [Calendar](/docs/calendar/teams) | A collective or round-robin event type takes its hosts from a team. Weight, priority and daily cap stay per person | Read each time hosts are listed or a slot is booked |
| [Support](/docs/cloud/support.md) | A conversation assigned to a team shows under **My teams** for its members. A private team's conversations are hidden from everyone else except org owners and admins | Read each time the inbox is listed |
| [Chat](/docs/cloud/chat.md) | A team channel's members are the team's. A private team gets a private channel | Stored rows, kept in step whenever a team's members change, and again whenever the channel list is read |

The apps' team pickers read `GET /api/workspace/teams` (the same tree as `org_team_list`, private teams only for
their members and org admins).

## What changes when

| Step | What you see |
|---|---|
| Done | Every Tasks team and every Notes team vault is also an org team, with the same id, members and roles |
| Done: Settings → Teams | One place to make teams and subteams, add members, set roles and mark a team private. Tasks' team settings and the team vault settings in Notes link there and no longer edit names or members themselves |
| Tasks (done) | Tasks reads org teams: subteams in the sidebar and team picker (a parent's lists include its subteams' issues), private teams hide their issues, projects, cycles and views from non-members, and team admins manage their team's Tasks settings ([Venom Tasks](/docs/cloud/tasks.md#teams)) |
| Notes (done) | A team vault belongs to an org team, and a parent team's members open its subteams' vaults. Notes shared with a team reach the same people. The team settings in Notes are vault settings only ([Notes team vaults](/docs/cloud/globe-team-vaults.md)) |
| People, Funnel, Outreach (done) | Sharing with a team follows membership down: a parent team's members see what is shared with its subteams; the share pickers show the org's tree; Outreach sequences can be shared with a team, and each member's enrollments send as them |
| All products (done) | Permissions follow the table above |
| Teams as targets (done) | On-call from a team, Calendar round robin from a team, Support assignment to a team, team channels in Chat ([below](#targets)) |
| SCIM (done) | Identity provider groups can sync into teams, and managed service staff can join them |

While products move, what stays in a product is what only that product has: in Tasks, the team key (the issue prefix),
workflow states, labels, estimates, cycles, templates, making a Tasks team and deleting one with its issues; in Notes,
opening a team's vault and closing an empty one. A change to an org team's name, description, archive state or members
shows up in Tasks and Notes, and the other way round.

Teams made in Settings → Teams show in Notes as soon as someone opens a vault for them, and in Tasks once someone adds
them there (Tasks → Settings → New team → **Or add a team from Settings → Teams**). A subteam made under a Tasks team is
a Tasks team at once.

A Tasks team and a Notes team vault with the same name, like "Engineering", are still two org teams (each kept its own
id). Notes doesn't merge them for you yet. To work in one, open a vault on the Tasks team, move the notes there and close
the old vault.

## For builders and agents

### Webhooks {#webhooks}

The org's webhooks (Settings → Webhooks) carry `org.team.created`, `org.team.updated` (renamed, re-keyed, made private
or moved, with what changed), `org.team.archived`, `org.team.member_added` and `org.team.member_removed`: the team's
id, key, name, parent, whether it is private, who did it, and the member (a person's or an agent's id) for a
membership change. Never the description. A private team's events are sent too: an endpoint is set up by an owner or
admin, who sees every team. Members synced from an identity provider (SCIM) are not sent one by one.

### MCP tools and REST {#api}

The `org_team_*` tools are on the workspace MCP server: connect only them with
`claude mcp add --transport http venom-org <your cloud>/workspace/mcp/org`. Each has a REST twin under
`/api/v1/org/teams` (OpenAPI at `/api/v1/openapi.json`), with the same credentials, rules and errors.

| Tool | REST | What it does |
|---|---|---|
| `org_team_list` | `GET /api/v1/org/teams?includeArchived=` | The tree of teams you can see |
| `org_team_get` | `GET /api/v1/org/teams/{teamId}` | One team, where it sits, its subteams and members |
| `org_team_create` | `POST /api/v1/org/teams` | `{name, key?, parentId?, private?, description?}` |
| `org_team_update` | `PATCH /api/v1/org/teams/{teamId}` | `{name?, key?, description?, private?}` |
| `org_team_move` | `POST /api/v1/org/teams/{teamId}/move` | `{parentId}`: a team's id, or `null` for the top level |
| `org_team_archive` | `POST /api/v1/org/teams/{teamId}/archive` | `{archived?}` (default true; false restores) |
| `org_team_members` | `GET /api/v1/org/teams/{teamId}/members?inherited=` | Members, with those from teams above (default) |
| `org_team_member_add` | `POST /api/v1/org/teams/{teamId}/members` | `{member, role?}`; adding someone already in it changes their role |
| `org_team_member_role` | `PATCH /api/v1/org/teams/{teamId}/members/{member}` | `{role}` |
| `org_team_member_remove` | `DELETE /api/v1/org/teams/{teamId}/members/{member}` | Take a person or agent out |

Who acts: a member's personal key or an OAuth grant acts as that member with their org role. A team key bound to a
service agent acts as that agent: it manages only the teams it is an admin of. A team key with neither only reads the
teams that are not private. OAuth connections need `org:read` to read and `org:write` to change; both are in the
default grant. A private team you cannot see answers "No such team", the same as a team that does not exist. Refusals
come back in words (REST: 403 for not allowed, 404 for not found, 422 for a conflict such as a cycle or the last admin).

### The team picker {#team-picker}

Console pages that ask "which team?" use one component, `components/org/TeamPicker.tsx`: the tree with a search box,
`<TeamPicker>` inline or `<TeamSelect>` as a button with a popover. Give it the tree (`listTeams()` on the server,
or `org_team_list`), the selected id (or ids with `multiple`) and `onChange`. `noneLabel` adds a row that picks
nothing ("No team"); `disabled` greys out teams that may not be picked, with the reason; archived teams show only with
`includeArchived`. It never fetches.

### Shapes

- The wire shapes are in `services/nodejs-cloud/contracts/org-teams.ts`, with a JSON Schema
  (`contracts/org-teams-v1.schema.json`) and fixtures. The tools take and return these shapes.
- A member is always written as a MemberRef string: `user:<clerk user id>` or `agent:<agent id>`.
- A synced team has `sync: {source: "scim", groupId, groupName}`; a member write on it answers 409 `team_synced`. A
  member who is a managed service's staffer has `msp: "<MSP org name>"`; making one an admin when the org does not
  allow it answers 403 `msp_team_admin`.
- The groups: `GET /api/admin/v1/sso/scim-groups` and `PUT /api/admin/v1/sso/scim-groups/{id}/team` with `{team_id}`,
  `{create: {name?, key?}}` or `{team_id: null}` (owners). The MCP tools are `admin_sso_group_list` and
  `admin_sso_group_team_set`.
- The design and the reasons for it are in ADR 0077 (`docs/adr/0077-org-teams.md` in the source repository).
