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):
| Mode | Contexts | Organizations |
|---|---|---|
hybrid (default) | Personal and organizations | Optional; the switcher lists Personal first |
organizations-only | Organizations only | Required: a user without one is sent to /onboarding/organization |
personal-only | Personal only | None: 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:
- It reads the user's memberships from the database (never trusting the session alone).
- 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. Inorganizations-onlymode 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
/apikeep 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).
- Every other request leaves the stale id in place and sees no active organization: actions and
- In
organizations-onlymode, with no active organization, it activates the one this browser used last (last-organizationcookie, used only if it matches a membership), else the first by name; a user with none goes to onboarding. - It puts the result on the request (
c.get('activeOrganization'), read with the helpers below) and inshared:
useShared() | Holds |
|---|---|
organization | The active organization { id, name, roles }, or null in the personal context |
organizations | Every 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:
| Section | Who | What |
|---|---|---|
| Name | Owners and admins (organization:update) | Rename; others see the name |
| Leave | Members, and owners with a co-owner | Leave; the only owner is told to delete or hand over first |
| Danger zone | Owners (organization:delete) | Delete, after an emailed code (Deleting) |
Click to expandSettings 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
| What | Where |
|---|---|
| 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) |
| Middleware | apps/web/middleware/08.organization.ts (its decisions: chooseActiveOrganization, organizationToRemember, needsOnboarding in @kit/organizations/server) |
| Settings page and actions | apps/web/pages/(app)/settings/organization.{tsx,server.ts} |
| Onboarding | apps/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 →