Account Modes

Configure personal, organization, or hybrid account modes for your SaaS.

Choose how users relate to data in your product: individual accounts only (B2C), organization accounts only (B2B), or both (hybrid, like GitHub). One setting derives the account, organization and billing feature flags.

This page is part of the Configuration documentation.

Quick Decision

If your product is...UseExample
For individuals, no collaborationpersonal-onlyNote-taking app, personal finance
For teams, always sharedorganizations-onlyProject management, team chat
For both individuals and teamshybridGitHub, Notion, Figma

If unsure: start with organizations-only for B2B or personal-only for B2C. Moving to hybrid later is easier than moving away from it.

Configuration

# apps/web/.env (or `void secret put ACCOUNT_MODE` when deployed)
ACCOUNT_MODE=hybrid # personal-only | organizations-only | hybrid
ENABLE_PERSONAL_ACCOUNT_BILLING=false

Any other value stops the app at startup: ACCOUNT_MODE: Expected one of personal-only, organizations-only, hybrid.

Derived Flags

getModeFeatureFlags() in @kit/organizations (packages/organizations/src/mode-flags.ts) turns the mode into these flags, which are part of getFeatureFlags() and useShared().config.flags:

Flagpersonal-onlyorganizations-onlyhybrid
enablePersonalAccounttruefalsetrue
enableOrganizationsfalsetruetrue
allowUserToCreateOrganizationfalsetruetrue
showAccountSwitcherfalsetruetrue
enableOrganizationsBillingfalsetruetrue
enablePersonalAccountBillingENABLE_PERSONAL_ACCOUNT_BILLINGfalseENABLE_PERSONAL_ACCOUNT_BILLING
enableOrganizationDeletionfalsetruetrue

Both billing flags also need the Stripe keys (STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET): without them, billing is off in every mode.

These flags can't be overridden one by one; change the mode instead. Sign-up, the account switcher, organizations and billing all read them.

Organizations-Only Onboarding

organizations-only has no personal context, so app pages can count on an active organization (except the account pages below). middleware/08.organization.ts makes sure of it on each signed-in request:

  • No active organization, but memberships: the organization this browser had open last becomes active, on the session too (else the first by name). The middleware remembers it in an HttpOnly cookie, last-organization, whenever the open organization changes; it's only a hint, used only if it names one of the user's organizations. This covers a new sign-in and leaving an organization: the user lands in the next.
  • No organizations at all: any pages/(app)/ page redirects to /onboarding/organization (authPaths.onboarding), a centred card with the create form and a sign-out link. Creating one lands on the page they asked for (kept as next), or the app home (APP_HOME_PATH).
  • Account pages stay open: /settings and every settings page in the account group (Profile, Security) open without an organization. To open another (app) page of yours, add its path to organizationOptionalPaths in apps/web/config/auth-paths.ts (empty by default). These pages render with organization: null.
  • /onboarding/organization sends a user who has an organization on to next (else the app home). In hybrid it opens too, as the step before paying for a plan picked on /pricing (afterSignUp), with a "Not now" link home; in personal-only it answers 404.

Switching an existing product to organizations-only sends users without an organization to onboarding on their next request.

Reading the Mode

// server
import { getAccountMode } from '#/config/account-mode.config.server.ts';
if (getAccountMode() === 'organizations-only') {
// ...
}
// browser: use the derived flags, not the mode string
const { config } = useShared();
if (config.flags.enableOrganizations) {
// render organization UI
}

Common Pitfalls

  • Checking the mode string in components. Check the specific flag, so one mode change updates every place.
  • Switching modes on a live product without a data migration: existing users keep the accounts they already have.
  • Expecting ENABLE_PERSONAL_ACCOUNT_BILLING to do anything in organizations-only.

Next: Feature Flags →