Teams Module

The Teams module manages access-boundary groups within an organisation. Source: packages/server/src/modules/teams/.

REST Endpoints

All endpoints are prefixed with /api/v1/teams and require ClerkAuthGuard.

Teams Service (services/teams.service.ts)

create(orgId, userId, dto)

Creates a new team. The creator is automatically added as OWNER. Input:

A URL-safe slug is generated from the name.

listForUser(orgId, userId)

Returns all teams where the user is either an owner or a team member.

getTeam(orgId, teamId, userId)

Returns a single team. Throws 403 Forbidden if the user is not a member of the team.

updateTeam(orgId, teamId, userId, dto)

Updates the team name. Only team members can update. The personal team name cannot be changed.

deleteTeam(orgId, teamId, userId)

Deletes a team and cascades to all workspaces and their resources. Personal teams cannot be deleted.

listMembers(orgId, teamId, userId)

Returns all team members with user data. Requires the requesting user to be a member of the team.

addMember(orgId, teamId, userId, targetUserId)

Adds a user to the team with the MEMBER role. The targetUserId must already be a member of the organisation. Idempotent — does nothing if already a member.

removeMember(orgId, teamId, userId, targetUserId)

Removes a user from the team. The team owner cannot be removed.

Personal Teams

Every user gets a personal team when they first join an org. Personal teams:

• Have isPersonal: true.
• Are auto-provisioned by AuthService.syncMembership() on first auth.
• Slug format: personal-{userId.slice(0, 8)}.
• Cannot be deleted.
• Contain the user's private workspaces.

Team Roles