Tenant modes — b2b, flat, b2c

Every Authio tenant has a mode field with three values:b2b, flat, or b2c. The mode is a pure UI hint — it only changes which dashboard surfaces are visible by default and which copy the onboarding wizard shows. Backend behaviour (authentication, sessions, audit, risk, API-key scoping) is identical across modes.

The three modes

B2B SaaS (mode = 'b2b', default)

For products sold to companies — Slack-, Linear-, Notion-style. Each of your customers is a sealed Organization with its own members, roles, SSO connection, SCIM directory, branded hosted-UI, audit slice, and FGA store. A single Authio user can hold memberships in many organizations (this is the marquee differentiator vs WorkOS).

The dashboard in b2b mode shows:

• The Organizations page at the top of the Identity nav
• An onboarding checklist that nudges toward “create your first organization” and “set up SSO”
• The KPI tile for organization count on the customer-home page

Consumer / Internal app (mode = 'flat')

For products sold to individuals (consumer apps) or used inside your own company (internal tools). There is no organization layer at all — users belong directly to your project and sign in to your app. Think Clerk’s default mode or Supabase Auth.

The dashboard in flat mode shows:

• Users as the primary Identity surface; Organizations is hidden from the sidebar
• /orgs renders an “Organizations are off in this tenant” banner with a link to Settings
• Empty-state copy that talks about “invite the first user” rather than “create an org”
• A user-centric KPI strip (no Organizations tile)

Hybrid (mode = 'b2c')

Same UI as flat today — no organizations in the sidebar, Users-first identity. The difference is the onboarding “What’s next” checklist: hybrid surfaces “add a social provider” and “customize the hosted-UI branding” rather than B2B prompts. Pick this when you’re starting flat but expect to layer organizations in later.

Picking a mode at onboarding

The dashboard onboarding wizard’s first step asks “What are you building?” with three radio cards: B2B SaaS,Consumer / Internal app, and Hybrid. Your selection becomes the new tenant’s mode. The default selection is B2B SaaS to preserve the WorkOS-killer positioning for users who land cold.

Switching modes later

The Settings page surfaces a mode-switch UI for the tenant owner. Transition rules:

• flat ↔ b2c: unconditional. Both render the same Users-first UX today.
• flat / b2c → b2b: unconditional. Additive — the Organizations layer appears in the sidebar; existing users keep their direct project access.
• b2b → flat / b2c: blocked when the tenant has at least one organization. The dashboard disables the switch button (tooltip: “Delete the N organizations first”) and the management-API rejects the PATCH with tenant_has_organizations as defense in depth. Delete or migrate the orgs first.

API surface

The mode is exposed through the dashboard’s session API (/v1/session/*):

• POST /v1/session/tenants accepts an optional mode field ("b2b", "flat", or "b2c"). Defaults to "b2b" when omitted.
• GET /v1/session/tenants/me returns mode on each tenant summary.
• GET /v1/session/tenants/:id returns mode and organizations_count on the detail.
• PATCH /v1/session/tenants/:id (owner-only) accepts { mode?, name?, slug? }. Emits a tenant.mode_changed audit event with from and to in metadata.

What does NOT change with mode

Auth-core endpoints, JWT issuance, passkey / magic-link / OAuth flows, risk decisions, audit emission, webhook delivery, the/v1/users and /v1/organizations API-key routes, pricing tiers, and MAU counting are all mode- agnostic. Your customer’s end-users sign in the same way regardless of which mode your tenant is in.