Organization context & switching

A user can belong to several organizations. At any moment, one of them is the active organization — the tenant the user is currently acting in. Your roles and permissions checks are always evaluated against the active organization.

Where the active org lives

The active organization id is carried in the user's session token. When you verify the token on your backend, you read both the user id and the active org id, and scope your queries to that tenant.

Switching organizations

Users switch the active org with an organization switcher — a menu of the orgs they belong to (plus their personal account). Atlas provides this UI in the hosted pages and as an SDK component, or you can build your own and set the active org through the SDK.

When the active org changes, Atlas issues a fresh session reflecting the new context and the roles the user holds there.

Personal account vs organization

A user acting under their personal account has no active org (no org-scoped roles apply). This is the right context for personal settings; organization data should only be reachable when an org is active.

Designing for multi-tenancy

• Always scope backend queries to the active org id from the verified token — never trust an org id sent from the client alone.

• Decide what happens when a user with no orgs signs in: prompt them to create one, or accept a pending invitation.

• Use webhooks (organization.created, organizationMembership.created) to provision tenant resources when an org or membership appears.

Next

Bring your biggest customers on board with enterprise sign-in → Enterprise SSO & SCIM.