Skip to main content

Tenant Switching

If you belong to more than one tenant in Shaari (for example, a parent company and its subsidiaries), you can switch between them without logging out. The tenant switcher provides a quick way to move between business entities while keeping your session active.

How to Switch Between Tenants​

The tenant switcher is located in the sidebar. It displays the name of the tenant you are currently working in.

To switch:

  1. Click on the tenant name or the switch icon in the sidebar.
  2. A dropdown or modal appears showing all tenants you have access to.
  3. Click on the tenant you want to switch to.
  4. The interface reloads with the selected tenant's data and settings.

The switch is immediate. After selecting a tenant, you are taken to the dashboard of that tenant with its data, navigation, and configuration loaded.

tip

The currently active tenant is displayed prominently in the sidebar at all times. Before creating any records, glance at the tenant name to confirm you are in the right context. This is especially important when you belong to multiple tenants with similar names.

What Changes When You Switch​

When you switch tenants, Shaari reloads the entire application context to reflect the selected tenant. Here is what changes:

Data​

All data on screen is replaced with the selected tenant's data. Invoices, customers, suppliers, products, employees, projects --- everything you see belongs to the active tenant. Data from the previous tenant is no longer visible.

Settings​

Tenant-specific settings take effect: company name, logo, VAT number, tax configuration, ZATCA integration status, and all other organizational settings. The sidebar may also reflect different module availability based on the tenant's subscription plan.

Permissions​

Your role and permissions may differ between tenants. If you are an Admin in one tenant and a Member in another, the interface adjusts accordingly. Menu items, action buttons, and data access reflect your permissions in the active tenant.

For example:

  • In Tenant A (Admin), you see all modules and can manage team members.
  • In Tenant B (Member with View Only for purchases), you can only browse purchase invoices and cannot upload, edit, or delete.

The sidebar navigation may change if the target tenant is on a different plan. For instance, if you switch from an Enterprise tenant (which has HR and Projects) to a Plus tenant (which does not), the HR and Projects menu items disappear.

Theme and Language​

Your personal preferences for language and dark/light mode persist across tenants --- they are tied to your user profile, not the tenant. However, the tenant's display name and logo in the sidebar update to match the active tenant.

Automatic Token Refresh​

When you switch tenants, Shaari performs a behind-the-scenes token refresh to ensure your session is valid for the new tenant context:

  1. The frontend sends a request to the backend indicating the target tenant.
  2. The backend verifies that your user account has access to the requested tenant.
  3. A new JWT token is issued with the correct tenant ID and your permissions for that tenant.
  4. The frontend stores the new token and uses it for all subsequent API requests.

This process is transparent --- you do not need to re-enter your password or take any manual action. If the token refresh fails (for example, if your access to a tenant has been revoked), you are redirected to a tenant you do have access to, with an appropriate notification.

note

If an Admin removes you from a tenant while you are actively using it, the next API request will fail authorization. Shaari handles this gracefully by switching you to another available tenant or prompting you to log in again if no tenants remain.

Tenant Switcher Visibility​

The tenant switcher is only visible if you belong to more than one tenant. If you have access to a single tenant, the sidebar shows your tenant name without a switch option, keeping the interface clean and uncluttered.

Common Scenarios​

Working Across Subsidiaries​

If you manage finances for both a parent company and a subsidiary, you might start your day reviewing the parent's sales dashboard, then switch to the subsidiary to upload purchase invoices. Each switch gives you a fully isolated workspace.

Different Roles in Different Tenants​

You might be an Admin in your own company's tenant but a Member with limited access in a partner's tenant. The tenant switcher respects these boundaries and adjusts the interface accordingly every time you switch.

Onboarding a New Subsidiary​

When a new subsidiary is created and you are added to it, the subsidiary immediately appears in your tenant switcher. You can switch to it right away and begin configuring settings and inviting team members.

Troubleshooting​

Tenant Not Appearing in Switcher​

If a tenant you expect to see is not listed, it means your user account has not been added to that tenant. Ask the Admin of the target tenant to invite you via Settings > Team.

Switch Fails or Loops​

If switching tenants causes an error or an infinite loading state, try the following:

  1. Refresh the browser page.
  2. Clear your browser cache and try again.
  3. Log out and log back in.

If the issue persists, your access to that tenant may have been revoked. Contact the tenant's Admin to verify your membership.