Organizations

Organizations, the active organization, the account switcher, settings, and which Better Auth endpoints are open.

An organization is a shared workspace: users belong to it as members with roles, and app data can belong to it. A signed-in user works in one context at a time: their personal account or one organization, the active organization.

This section covers the kit's core: create, switch, rename, leave and delete, and inviting members. Changing roles and removing members are in Members; roles and permissions in Roles and Permissions.

Account Modes

ACCOUNT_MODE decides which contexts exist (Account Modes):

ModeContextsOrganizations
hybrid (default)Personal and organizationsOptional; the switcher lists Personal first
organizations-onlyOrganizations onlyRequired: a user without one is sent to /onboarding/organization
personal-onlyPersonal onlyNone: no plugin, no endpoints, no pages (404), no switcher

The Active Organization

It's stored on the Better Auth session (session.activeOrganizationId), not in the URL. apps/web/middleware/08.organization.ts resolves it on every signed-in request, pages and /api alike:

  1. It reads the user's memberships from the database (never trusting the session alone).
  2. If the session points at an organization the user no longer belongs to (left, removed, deleted), that organization is never used. The next page request under (app) clears it and goes to the app home with a notice ("You no longer have access to that organization"), so a member removed while a page was open never lands on a 404. In organizations-only mode a user left with no organization goes to onboarding instead.
    • Every other request leaves the stale id in place and sees no active organization: actions and /api keep their 404/409, and assets and hover prefetches don't use up the notice (a prefetch gets an empty 204, so the click loads the page itself).
  3. In organizations-only mode, with no active organization, it activates the one this browser used last (last-organization cookie, used only if it matches a membership), else the first by name; a user with none goes to onboarding.
  4. It puts the result on the request (c.get('activeOrganization'), read with the helpers below) and in shared:
useShared()Holds
organizationThe active organization { id, name, roles }, or null in the personal context
organizationsEvery organization the user belongs to, { id, name }, by name

shared never holds other members' data.

The Account Switcher

At the top of the sidebar (AccountSwitcher from @kit/organizations/ui): Personal (hybrid only), the user's organizations with the active one checked, and Create organization. Choosing one calls Better Auth's set-active, which checks the membership, and re-renders the page in the new context without a full reload.

Creating an organization (a name of 1 to 64 characters; the slug is generated on the server) makes it active and lands on the app home. A user can own up to MAX_ORGANIZATIONS_PER_USER (default 5; 0 for no limit), and creating is limited to 5 a minute per IP.

Settings

/settings/organization, in the sidebar while an organization is active:

SectionWhoWhat
NameOwners and admins (organization:update)Rename; others see the name
LeaveMembers, and owners with a co-ownerLeave; the only owner is told to delete or hand over first
Danger zoneOwners (organization:delete)Delete, after an emailed code (Deleting)
Settings for the active Acme Studio organization.Click to expand

Settings for the active Acme Studio organization.

Open Endpoints

Better Auth's organization plugin has about 30 endpoints. Over HTTP only two answer: /api/auth/organization/create and /api/auth/organization/set-active. Every other /organization/* path is 404 (organizationScope in packages/better-auth/src/organization.ts, OPEN_PATHS). Rename, leave and delete are page actions that call auth.api.* on the server after the kit's own checks.

Keep the others closed. If you must open one, decide first who may call it and what it checks, add it to OPEN_PATHS with a test, and never call a closed one from the browser.

Where Things Are

WhatWhere
Services (memberships, rename, leave, delete, invitations, deletion codes)packages/organizations (@kit/organizations)
Request wiring and guards (organizationsFor(c), requireActiveOrganization)apps/web/lib/organizations.server.ts (deps: apps/web/config/organizations.server.ts)
Middlewareapps/web/middleware/08.organization.ts (its decisions: chooseActiveOrganization, organizationToRemember, needsOnboarding in @kit/organizations/server)
Settings page and actionsapps/web/pages/(app)/settings/organization.{tsx,server.ts}
Onboardingapps/web/pages/onboarding/organization.{tsx,server.ts}
After-delete hooks (yours)apps/web/config/organization-hooks.config.server.ts
Better Auth rules (slug, names, cap, allowlist)packages/better-auth/src/organization.ts, organization-rules.ts

Next: Scoping Your Data →