DOCS/Platform Docs/Dashboard/Org Switching

Org Switching

Organization switching is a conditional control in the current dashboard, not a universal one. Use this guide only if the top bar shows an org selector instead of a fixed org name.

The dashboard top bar without an established current organization context.
The org control is context-dependent, so some sessions start without a visible organization label.

When The Switcher Appears

  • The top bar renders the org switcher when you are signed in, an active org exists, and the dashboard session user has platform role super_admin. This visibility check does not require the active org to be a system org. The organization/user area is hidden below the sm breakpoint, so use a wider viewport to inspect or switch organization context.
  • Other platform roles see a static org label, regardless of the active organization’s system flag.
  • If there is no current org context, the switcher does not render at all.
The dashboard top bar showing a fixed organization label instead of a switcher.
A fixed org label is the normal state when the current context does not expose multi-org switching.

Step-By-Step

  1. Look at the top bar and confirm that the current org name appears with a dropdown indicator.
  2. Open the dropdown and review the list of organizations available to your session.
  3. Select a different org only when you need to change operational context.
  4. Wait for the dashboard to finish switching before you continue your work.
  5. Confirm the top bar now shows the org you intended to use.

What The Menu Means

  • The currently active org is highlighted in the menu.
  • The menu list comes from the platform super-admin org-list endpoint, not a general membership-list endpoint. That API requires super_admin plus system-org membership; a system-org UI label alone does not grant it.
  • For platform super_admin sessions, switching to a non-system org keeps the selector available so you can switch back. OrgContext uses that same platform role to fetch the list; system-org membership alone does not enable listing. Server checks remain authoritative.
  • System orgs are labeled so you can tell when you are operating inside a privileged context.
  • A New Organization action may appear in this menu, but that is not the ordinary onboarding path described in Getting Started.

Guardrails

  • Do not assume every authenticated user can switch orgs. Navbar visibility uses the platform role; Better Auth independently authorizes switching, and the custom org-list endpoint has its own stricter access gate.
  • Do not assume every authenticated user can create a new org. Backend org creation is reserved for controlled admin flows rather than normal first-use onboarding.
  • If you expected the switcher and only see a fixed org name, treat that as a visibility rule, not a broken UI.

If You Cannot Switch

  • If the switcher is missing, confirm that you are in the correct org and that your current context actually exposes multi-org controls.
  • If the menu opens but does not list the org you need, ask your operator to verify your memberships before you continue.
  • If a switch fails after you choose a different org, reload once and then escalate to your operator if the dashboard stays on the old context.