Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Subteams

Split an Enterprise team into subteams, each with its own members and Spaces, on the parent's plan and seats

Enterprise

A subteam is a team inside your team. It has its own name, URL, members, and Spaces. It uses the parent team’s plan, seats, and billing.

Subteams need an Enterprise parent team. On every other plan, subteam operations return enterprise_required. Plans are on Plans and billing.

How subteams work

  • The parent’s owners and admins are in every subteam. They hold the same role there. To change that role, change it on the parent team.
  • Parent members can join a subteam. Parent members see it on the parent team’s Subteams page, and under the parent team on Teams, with Join. Pressing Join makes them a subteam member, with no new seat. A person removed from a subteam does not see it there. An owner or admin of the parent team must add them again.
  • Seats are shared. Seats count across the parent and all its subteams. A person in several teams of the family uses one seat.
  • Subteams do not nest. A subteam cannot have subteams of its own.
  • Leaving the parent leaves every subteam. When someone leaves or is removed from the parent team, they also lose every subteam membership.

Each subteam owns its Spaces. Access to them follows subteam membership and the member’s subteam role. Teams, roles, and Space ownership work as described in Teams and members.

Create a subteam

Any member of the parent team can create a subteam and becomes its admin. To keep creation with owners and admins, turn on Only owners and admins can create subteams in the parent’s Team settings → Access.

  1. Open the parent team and go to Subteams.
  2. Press New Subteam.
  3. Enter a Name, then press Create Subteam.

Spacefast creates the subteam and opens it. Its URL slug starts with the parent’s slug, followed by the name.

Over HTTP, send createSubTeam with a name of 1 to 255 characters:

curl "https://api.spacefast.com/v1/teams/$TEAM_ID/subteams" \
  -H "Authorization: Bearer $SPACEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Design"}'

The 201 response holds the subteam: id, teamId (the parent), name, slug, memberCount, createdAt, and updatedAt. From a terminal, run sf teams subteams create Design.

List subteams

listSubTeams returns the parent’s subteams, sorted by name. Every member of the parent team can list them. From a terminal, run sf teams subteams list.

The Subteams page shows the subteams you are in, each with Open. Below them are the subteams you can join, each with Join.

Rename a subteam

Send updateSubTeam with a new name. The slug does not change. From a terminal:

sf teams subteams rename "$SUBTEAM_ID" "Brand design"

You can also open the subteam and rename it in Team settings → General.

Manage subteam members

Adding and removing members needs an owner or admin of the parent team.

sf teams subteams members list "$SUBTEAM_ID"
sf teams subteams members add "$SUBTEAM_ID" "$USER_ID"
sf teams subteams members remove "$SUBTEAM_ID" "$USER_ID"
Operation What it does
listSubTeamMembers Lists members with id, subTeamId, userId, createdAt, and a user object holding id, name, email, and image. Subteam members and the parent’s owners and admins can read it
addSubTeamMember Adds a parent member as a subteam member. No invitation is sent and no seat is used. Repeating the request keeps one membership
removeSubTeamMember Removes the person from the subteam and its Spaces. They stay on the parent team

Find a user ID with sf teams members ls --json on the parent team. You can also invite someone from the Members page of the subteam. The subteam role picker offers Admin and Member. A subteam has no owner of its own.

A person you remove from a subteam cannot rejoin it with Join. To bring them back, add them again.

Delete a subteam

A subteam with Spaces cannot be deleted. Delete or move its Spaces first. See Move a Space to another team.

Send deleteSubTeam, or run sf teams subteams delete <subteam-id>. In the dashboard, open the subteam and go to Team settings → Danger Zone → Delete this team. Deleting a subteam ends its memberships.

A parent team cannot be deleted while it has subteams. Delete every subteam first.

Errors

Code Status Meaning
enterprise_required 403 The parent team is not on Enterprise
parent_authority_required 403 Restoring a deleted subteam, or changing a setting the parent team controls, needs an owner or admin of the parent team
subteam_nesting_unsupported 422 The team is already a subteam, or it is a system or partner team
role_managed_by_parent 409 The person’s subteam role comes from the parent team. Change it there
role_managed_by_parent 422 A subteam has no owners of its own. Grant or invite Admin or Member
team_has_spaces 409 The subteam still has Spaces
team_has_subteams 409 The parent team still has subteams
not_found 404 The subteam does not exist, or the user is not a member of the parent team
forbidden 403 Your role cannot manage members, or you are not in the subteam whose members you asked for

Last updated on

Was this page helpful?