Organization Defaults
Reserved organization slugs and a default active organization for new sessions.
Every Better Auth project ships organizationDefaults(), a Better Auth plugin the compiler emits into src/plugins/organization-defaults/ and adds to src/lib/auth.ts alongside organization(). It needs no configuration.
Reserved organization slugs
An organization slug becomes a URL segment: /account/<slug> in the Account UI, and <appUrl>/<slug> in your app with the default tenantPattern. A slug that matches a route shadows it. An organization called security could never open its own page, and one called admin or support impersonates something it isn't.
The plugin refuses about 150 reserved slugs with 400 and code: "ORGANIZATION_SLUG_RESERVED" on:
POST /auth/v1/organization/createPOST /auth/v1/organization/update(renaming the slug)POST /auth/v1/organization/check-slug, so the Account UI's "is this URL available" check agrees with the write- the operator route
POST /auth/v1/admin/create-organization, which writes the row directly and applies the same rule
Matching is exact and case-insensitive: home is reserved, home-depot is not. The list covers:
- every top-level Account UI route (
home,profile,security,dashboard,login, …) - auth and account words (
settings,billing,members,invite,oauth, …) - platform paths (
api,cms,app,static,webhooks,www, …) - roles and system accounts (
admin,root,sysadmin,superuser,system, …) - common shell commands (
sudo,ls,rm,cd,git,curl, …) - values that read as code (
null,undefined,true,localhost,env, …)
The full list is RESERVED_ORGANIZATION_SLUGS in src/plugins/organization-defaults/reserved-slugs.ts. A compiler test fails if a new top-level Account UI route is missing from it.
Organizations that already hold a reserved slug keep it. Updates that don't change the slug still work, but the org's Account page is shadowed by the route until it is renamed.
Default active organization
New sessions start with no active organization, so the app, the CMS, and org-scoped API calls have nothing to default to. The plugin fills that gap when the choice is unambiguous:
- Pinned project (
features.pinnedOrganizationId): a member of the pinned organization starts every session in it. - One membership: the session starts in that organization.
- Several memberships, or none: nothing is chosen; the user picks an organization in the app or the Account UI.
It never overrides an active organization the session already carries. The Account UI applies the same rule client-side for sessions created before the plugin existed.