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.
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 | 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 |
"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:writescope does not let a viewer share contacts. One exception for now: in Comms, an app withcomms:writecan 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>oragent:<agent id>. - A synced team has
sync: {source: "scim", groupId, groupName}; a member write on it answers 409team_synced. A member who is a managed service's staffer hasmsp: "<MSP org name>"; making one an admin when the org does not allow it answers 403msp_team_admin. - The groups:
GET /api/admin/v1/sso/scim-groupsandPUT /api/admin/v1/sso/scim-groups/{id}/teamwith{team_id},{create: {name?, key?}}or{team_id: null}(owners). The MCP tools areadmin_sso_group_listandadmin_sso_group_team_set. - The design and the reasons for it are in ADR 0077 (
docs/adr/0077-org-teams.mdin the source repository).