0037. Resources move between teams

Status: accepted, 2026-10-30

Context

Every team-owned resource (a mail domain, a site, an app, a monitor, a key…) was created in a team and stayed there: moving one meant deleting it and making it again, losing its history, its addresses and everything hanging off it. ADR 0005 gives team owners "transfers", but no service had one.

Decision

One contract in every service: POST /api/v1/<resources>/{id}/transfer {"team_id": "…"} moves a resource and everything that belongs to it to another team, in one transaction, and answers the resource as it is now. The CLI's xvii <service> <resource> transfer ID --team T and a panel action ("Move to team…", with a team picker and a confirmation naming both teams) call it. MCP tools follow the API (ADR 0028).
Who: an owner of the team it leaves and an admin (or owner) of the team it joins; superusers any. A personal team counts like any other team its person owns.
What moves: the resource, its children and their history (usage, logs, deliveries) keep their ids and addresses; only the owner changes. A project of the old team doesn't follow: the resource leaves its project (no project in the new team) unless a project of the new team is named (project_id).
Limits: the joining team's limits (ADR 0013) are checked for what arrives (counts, storage) before anything moves; a transfer that would pass them is refused and nothing moves. Usage already counted this month stays with the team it was counted for.
What stays: grants and access given inside the old team (people's access, shares to its members, team-scoped tokens and keys of other resources) don't travel: they stop applying. Things that can't leave without breaking (a resource another of the old team's resources depends on) are refused with the dependency named.
Journal and events: both teams' journals record <resource>.transfer with from and to; the joining team hears through notify.

As built (2026-10-30)

Service	What moves (`POST …/transfer`)	Notes
mail	`/domains/{name}`: mailboxes, aliases, their mail, submissions, queue	refused while a mailbox's owner isn't in the joining team; app passwords of non-members stop; owner TXT rewritten
domains	`/zones/{id}` (xvii name servers), `/accounts/{id}` with its domains	a Cloudflare domain moves with its account; attached names follow
pages	`/aliases/{name}` with every deploy it served	refused while another alias serves one of them
tunnel	`/names/{name}`	an open tunnel is closed
apps	`/apps/{id}` (+previews; needs a project and environment), `/nodes/{id}`, `/registries/{id}`	placement checked as the new team; running containers stay in the old network until the next deploy
env	`/sets/{id}`	references checked in the new team; `force` as for delete
config	`/flags/{id}`, `/configs/{id}` (needs a project)	values of environments the new project lacks are dropped and listed
status	`/monitors/{id}`, `/pages/{id}` with its monitors	automatic monitors follow their app or site
errors	`/projects/{id}`	DSN kept; links to the old team's apps undone
analytics	`/sites/{id}`	key and share link kept; links undone
hooks	`/endpoints/{id}`	requests (headers included) and secret go along
share	`/drops/{code}`	old links on the old team's hosts keep working
notify	`/channels/{id}`, `/topics/{id}`	a topic old-team channels listen to is refused
ai	`/keys/{id}`, `/accounts/{name}`, `/upstreams/{name}`	a person's key only to a team they're in, within their access there

Consequences

Moving a domain, a site or a monitor keeps its DNS, certificates, URLs and history.
Every service carries the same endpoint, check and panel action; a service whose resource can't move (it names an external owner, say) documents why.