---
id: UJ-004
title: Switch the active tenant
actors: [multi-tenant user]
surface: app.zync.is
goal: Start work in another tenant membership without carrying data or permissions across tenants.
trigger: Authenticated user selects another tenant from the tenant switcher.
preconditions:
  - User has at least two active tenant memberships.
success_state: New session has the selected tenant `tid`, role, permissions, tier, and tenant-scoped data.
source_specs:
  - docs/specs/2026-05-30-foundation-auth-rbac.md
  - docs/specs/2026-05-30-tenant-portals.md
---

## Happy path

1. User opens tenant switcher → Zync lists only memberships visible to that user.
2. User selects a tenant → Zync issues a new session containing the selected tenant `tid` and expanded permission set.
3. App reloads tenant-scoped navigation/dashboard → data and module availability reflect the selected tenant.

## Alternate and failure paths

- Membership is frozen, revoked, or no longer exists → deny switch and keep the current tenant session.
- New session issuance fails → preserve current tenant and show retry.

## Permissions and boundaries

- Tenant ID, role, permissions, tier, caches, and queries resolve from the active membership.
- Never reuse a prior tenant's data response after switching.

## Source specs

- `docs/specs/2026-05-30-foundation-auth-rbac.md`
- `docs/specs/2026-05-30-tenant-portals.md`