Next.js Workspace Switching: Tenant Context, Caches & Permissions

Separate user identity from the selected workspace

A person can belong to several organizations with different roles, plans, data, and policies. Switching a label in the navigation bar is only the visible part of changing workspace. Requests, caches, drafts, subscriptions, and background actions must agree on the organization they concern.

Keep context immutable for the lifetime of a request. A mutable global active-tenant variable can let concurrent requests influence each other. Construct trusted context at the server boundary and pass it through the work it owns.

Choose a route model that keeps deep links unambiguous

Workspace path segments or subdomains can make context explicit in bookmarks and separate browser tabs. If a session-wide preference supplies the default workspace, define how it interacts with existing tabs. A preference change should not silently retarget an already open mutation form.

Resolve a route slug to a stable internal tenant ID and verify membership before rendering private content. Handle renamed and removed workspaces deliberately. An unknown or forbidden workspace should produce a safe recovery screen without revealing private organization details.

Authorize membership and resources on every request

A browser-supplied workspace ID is a selector, not proof of access. Resolve identity, validate current membership and tenant status, and apply action-specific permissions. Load resources through queries scoped to the resolved tenant.

// Illustrative boundary
const actor = await requireSession(request);
const context = await requireWorkspaceAccess(actor, routeWorkspace);
const project = await projects.find({
  tenantId: context.tenantId,
  projectId: requestedProjectId,
});
await requirePermission(context, "project:update", project);

Do not trust a cached role indefinitely after membership revocation. Define permission-cache freshness and invalidation, especially for sensitive operations. Database policy can provide another boundary; see our row-level security guide.

Scope server and browser caches to their actual audience

Include tenant identity in every workspace-dependent data key. Add user, role, locale, or policy version where those change the permitted representation. A key containing only a project ID is unsafe when IDs or representations can overlap across organizations.

On a switch, stop displaying old workspace data while the next authorized view loads. Cancel obsolete fetches and ignore late responses whose context no longer matches. Avoid keeping previous data as a placeholder across tenant boundaries. Clear or partition optimistic mutations and selection state as well as ordinary query caches.

The data-fetching guide covers cache ownership and request boundaries.

Bind unsaved work and commands to their original workspace

Key drafts by user, workspace, resource, and schema version. Before switching, explain whether unsaved changes are saved locally, discarded, or require a decision. Never reuse one generic draft key across organizations.

Capture the workspace when a mutation starts and keep that context through retries and completion callbacks. A slow save from workspace A must not refresh workspace B or show a success message naming the wrong record. Re-authorize on the server even when the command carries a valid original context.

Rebind subscriptions and restore state after switching

Unsubscribe from the previous workspace before subscribing to another, and authorize each channel on the server. Tag client events with workspace identity and discard mismatched messages. Clean up presence, notification counts, streaming requests, and listeners.

On reconnect, fetch durable state under the current context rather than assuming the client received every live event. If membership is revoked while connected, terminate or restrict the subscription and present a safe navigation path.

Persist context for jobs and downloads

A queued report, import, or bulk action should store its tenant, requester, resource scope, and operation ID explicitly. Workers must not look up whichever workspace the user selected most recently. Recheck authority according to the action policy before delayed sensitive work.

Downloads and job-status endpoints need their own authorization checks. An operation created in one workspace must remain there after switching. The bulk-action guide explains durable manifests and per-record outcomes.

Keep organization identity clear at consequential moments

Show the workspace name consistently in navigation, settings, billing, invitations, and confirmation screens. For high-impact actions, name the workspace and scope in the confirmation so users can detect a mistaken selection.

Make the switcher keyboard accessible, label the current selection, and announce the completed transition without repeatedly interrupting the user. When access disappears, explain the unavailable state and offer other authorized workspaces rather than leaving an empty loading screen.

Test cross-workspace timing and isolation

Use a test user with different roles in two organizations. Switch while requests are slow, while a mutation commits, while a notification arrives, and while a report finishes. Verify that content, counts, success messages, and downloads remain correctly scoped.

Test two tabs with different workspaces, restored browser history, renamed slugs, revoked membership, stale role caches, local drafts, and repeated commands. Correlate server logs with actor and tenant IDs without logging private payloads. A useful invariant is that every result can be traced to the same context as the request that created it.

Workspace switching checklist