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.

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 thesmbreakpoint, 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.

Step-By-Step
- Look at the top bar and confirm that the current org name appears with a dropdown indicator.
- Open the dropdown and review the list of organizations available to your session.
- Select a different org only when you need to change operational context.
- Wait for the dashboard to finish switching before you continue your work.
- 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_adminplus system-org membership; a system-org UI label alone does not grant it. - For platform
super_adminsessions, 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 Organizationaction 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.