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... | Use | Example |
|---|---|---|
| For individuals, no collaboration | personal-only | Note-taking app, personal finance |
| For teams, always shared | organizations-only | Project management, team chat |
| For both individuals and teams | hybrid | GitHub, 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 | hybridENABLE_PERSONAL_ACCOUNT_BILLING=falseAny 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:
| Flag | personal-only | organizations-only | hybrid |
|---|---|---|---|
enablePersonalAccount | true | false | true |
enableOrganizations | false | true | true |
allowUserToCreateOrganization | false | true | true |
showAccountSwitcher | false | true | true |
enableOrganizationsBilling | false | true | true |
enablePersonalAccountBilling | ENABLE_PERSONAL_ACCOUNT_BILLING | false | ENABLE_PERSONAL_ACCOUNT_BILLING |
enableOrganizationDeletion | false | true | true |
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
HttpOnlycookie,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 asnext), or the app home (APP_HOME_PATH). - Account pages stay open:
/settingsand every settings page in theaccountgroup (Profile, Security) open without an organization. To open another(app)page of yours, add its path toorganizationOptionalPathsinapps/web/config/auth-paths.ts(empty by default). These pages render withorganization: null. /onboarding/organizationsends a user who has an organization on tonext(else the app home). Inhybridit opens too, as the step before paying for a plan picked on/pricing(afterSignUp), with a "Not now" link home; inpersonal-onlyit answers 404.
Switching an existing product to organizations-only sends users without an organization to onboarding on their next request.
Reading the Mode
// serverimport { getAccountMode } from '#/config/account-mode.config.server.ts';if (getAccountMode() === 'organizations-only') { // ...}// browser: use the derived flags, not the mode stringconst { 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_BILLINGto do anything inorganizations-only.
Next: Feature Flags →