Units and teams

Units and teams model nested membership inside an organization:


organization
└── unit
    └── team

Use them when a stable department or working group needs its own share target or administrative scope. Groups are often simpler for ad hoc sharing.

Stored roles

Scope	Roles
Unit	`unit_admin`, `base_creator`, `base_approver`, `member`
Team	`team_lead`, `variant_creator`, `variant_deployer`, `variant_user`

unit_admin and team_lead have defined membership-management authority in the organization API. The creator/approver/deployer labels express intended workflow responsibilities, but their presence does not prove enforcement by every build or deployment endpoint. Test the specific workflow.

Membership rules

A unit belongs to one organization.
A team belongs to one unit.
A user must be an organization member before joining a unit or team.
A team member should also be in the parent unit; administrative routes enforce the hierarchy when adding members.
Organization owners/admins and scoped administrators have different management powers, described in Roles and Permission Scope.

Design guidance

Create a unit only if it has a durable boundary such as ownership, approval responsibility, or a distinct resource-sharing scope. Create a team for a smaller working group inside that boundary.

Example:


Acme
├── Platform unit
│   ├── Image engineering team
│   └── Security review team
└── Product unit
    └── Device application team

Do not encode an org chart that has no effect on authorization. Extra nesting increases the chance of stale memberships and unexpected inherited shares.

Safe changes

For an add, role change, or removal:

record organization, unit, team, user, and current roles;
make one change;
test a permitted operation;
test a denied operation;
refresh or reauthenticate to detect stale session behavior; and
review shares whose target membership changed.

Users can belong to multiple units and teams. Adding a new membership does not transfer or remove an old one.

Deletion boundary

Deleting a unit or team is a material operation. Do not rely on generic statements such as “resources become unit-level” or “unassigned resources are archived.” Before deletion, use read-only inventory to identify memberships, shares, dependent resources, active work, and external references. Export the required audit record and confirm the deployed release’s exact cascade behavior.

If the impact is not clear, remove broad sharing and members first, preserve the object, and seek owner approval before deletion.