Skip to content
Docs menu

Teams, subteams and roles

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.

View .md

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 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), 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 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

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).

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) 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

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 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 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 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 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)
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)
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)
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

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

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

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).