Skip to main content

Workspaces & switching clinics

Use workspaces when the same staff login belongs to more than one clinic workspace. Achal links tenant-specific user records to a global account so users can switch without signing in again.

Who can do this: Any signed-in staff user with active linked memberships can view and switch workspaces. Admins with users.manage can send account-link invitations to employees with login email addresses. Where: Header Workspace switcher, My workspaces (/app/account/workspaces), employee Invite to link login action.

My workspaces page with linked clinics and invitation form

Before you start​

  • The same person must have a user record with the same email address in each workspace.
  • A workspace membership must be ACTIVE. SUSPENDED memberships cannot switch in.
  • The tenant user remains authoritative for role, branch, password and login-enabled status.
  • Switching workspace performs a full page reload to clear old tenant data from memory.

Switch from the header​

  1. Look at the header for Workspace.
  2. Open the workspace dropdown. Result: The switcher appears only when your login has more than one active membership.
  3. Choose the clinic workspace name. Result: The hidden status says Switching workspace… while the server verifies membership.
  4. Wait for the page to reload. Result: Achal opens the default page for your role in the new workspace.
caution

Switching workspace wipes offline data on this device. Sync offline changes before switching.

Use My workspaces​

  1. Open /app/account/workspaces. Result: The page title is My workspaces and it lists Workspaces your login is linked to. Switch without signing in again.
  2. Review linked clinics. The active one shows Current.
  3. Click Switch on another workspace. Result: Achal calls tenant switch and then performs a hard reload into the new session.
  4. If only one workspace is linked, the page says Your login is linked to this workspace only.

Accept an invitation from another workspace​

  1. Ask an administrator of the other workspace to send an account-link invitation.
  2. Open My workspaces in the workspace where you are currently signed in.
  3. Under Link another workspace, enter Invitation ID.
  4. Enter the 8-digit code from the invitation email.
  5. Click Link workspace. Result: The message says Workspace linked. and the list refreshes.
  6. Click Switch if you want to move to the newly linked workspace.
tip

The invitation ID starts with inv_. The code is exactly 8 digits and expires after 24 hours.

  1. Open Employees.
  2. Find an employee who has a login email and is not login-disabled.
  3. Click Invite to link login. Result: If email is sent, the message says Invitation e-mailed.
  4. If the mail service could not send, the message says Invitation created, but the e-mail could not be sent. Check the e-mail settings.
  5. Give the employee the invitation ID and 8-digit code through an approved channel if needed.
Employees page with Invite to link login action

What happens during a switch​

  1. Achal sends the target tenantId to the backend.
  2. The backend checks that your current account has an active membership in the target workspace.
  3. The target workspace user must be active, login-enabled, linked to the same account and have the same email.
  4. The old token is blacklisted and a new token is issued for the target tenant.
  5. The frontend calls window.location.assign, not router navigation. Result: Caches, dashboard cards, onboarding state and page data are reloaded for the new tenant.

Suspended membership​

  1. If an admin suspends a membership, the user record remains in the tenant but the global account cannot switch into it.
  2. Attempting to switch shows Could not switch workspace. Please try again.
  3. The user must contact the workspace owner.

Troubleshooting​

Problem / messageWhat it meansWhat to do
Could not switch workspace. Please try again.Switch API failed or membership is not active.Retry. If it repeats, ask the target workspace owner to check your user status and membership.
NO_ACTIVE_MEMBERSHIP You do not have an active membership in that workspaceYou are not actively linked to the target tenant.Ask an admin to invite or reactivate the membership.
Could not load your workspaces.Membership list failed.Reload the page.
Enter the invitation ID and the 8-digit code.Invitation form failed client validation.Enter an ID like inv_... and exactly 8 digits.
The invitation could not be accepted. (code)Backend rejected the invitation and returned a code.Match the code below and retry if appropriate.
INVITE_NOT_FOUND Invitation not foundID is wrong, belongs to another email, or target user cannot be found.Check the email and invitation ID. Ask admin to resend.
SAME_TENANT You are already signed in to that workspaceInvite belongs to current tenant.No action needed. Use the current workspace.
INVITE_NOT_PENDING This invitation is no longer validInvite was accepted, locked, cancelled or otherwise not pending.Ask admin to create a new invite.
INVITE_EXPIRED This invitation has expiredInvite is older than 24 hours.Ask admin to create a new invite.
INVITE_LOCKED Too many wrong codesFive wrong attempts locked the invite.Ask admin to send a new invite.
INVALID_CODE The code is not correct8-digit code does not match.Re-enter carefully.
ACCOUNT_CONFLICT This employee record is linked to a different accountTarget employee is already linked elsewhere.Ask the owner to review employee records.
ALREADY_LINKED Already linked.Employee already has a membership link.Use switcher; no new invite needed.
USER_NOT_FOUND User not foundAdmin tried to invite a missing employee.Refresh Employees and try again.
VALIDATION_FAILED The employee needs a login e-mail to be linkedEmployee lacks login email or login is disabled.Add a login email and enable login before inviting.
MEMBERSHIP_NOT_FOUND This employee is not linked to an accountAdmin tried to suspend/reactivate a non-linked membership.Send an invite first.