Add Organization Settings and Invitations to BTST Better Auth UI
Connect the Better Auth server and browser plugins to BTST organization pages, use the correct invitation URL, and keep business-data access scoped.
Organization settings require three connected pieces: Better Auth's server plugin, its browser client plugin, and the BTST companion's organization pages. Adding a members screen alone does not create the endpoints, schema, or membership rules behind it.
This guide covers the wiring for @btst/better-auth-ui@2.0.0, its supported Better Auth 1.6.16 dependency group, and BTST v3. Start from a working auth integration. The default BTST auth scaffold enables auth and account pages; organizations are an explicit addition.
Configure the server before exposing the pages#
Add Better Auth's organization() plugin to your existing server configuration. Preserve the current database adapter, auth providers, secrets, and other plugins. Generate and apply the corresponding schema changes using the migration workflow for that application's adapter.
The application also owns organization creation policy and invitation delivery. Choose who can create an organization, which roles members can assign, and how invitations reach recipients. Better Auth's organization documentation describes these server capabilities; verify the options against your pinned version when following newer examples.
If email invitations are part of your flow, implement the server's invitation email callback. An invitation row and a working email delivery path are separate outcomes. Test both in your own development environment.
Extend the existing browser client#
Add the organization client plugin to the same client the companion already receives:
import { createAuthClient } from "better-auth/react";
import { organizationClient } from "better-auth/client/plugins";
export const authClient = createAuthClient({
basePath: "/api/auth",
plugins: [organizationClient()],
});
This is a minimal client example. Preserve any existing client plugins, cross-origin configuration, or other settings. Keep one stable browser client instead of recreating it during each component render.
Register the companion's organization routes#
Use the companion factories in the existing client stack's plugins object:
import {
accountClientPlugin,
authClientPlugin,
organizationClientPlugin,
} from "@btst/better-auth-ui/client";
export const authPagePlugins = {
auth: authClientPlugin(),
account: accountClientPlugin(),
organization: organizationClientPlugin(),
};
Retain your application's other plugins when merging this object. Shared API and site paths, plus the QueryClient, still belong in createClientStack().
In the provider, keep authClient under overrides.auth, retain the framework's onSessionChange callback, and add organization: { organization: true } under overrides. Account settings can remain under account: { account: true }. The companion bridge reads those three override groups and derives the route bases from the resolved stack runtime.
With a site base path of /pages, the organization members route is /pages/organization/members, and organization settings is /pages/organization/settings. If your application uses /p, substitute that prefix. The account's organization list is a separate page at /pages/account/organizations.
Build the invitation URL for the installed companion#
The released companion's acceptance card reads the invitationId search parameter. For the default mount, an invitation link has this shape:
https://app.example/pages/auth/accept-invitation?invitationId=INVITATION_ID
Construct the link on the server from your trusted application origin and the newly created invitation ID. URL-encode the value. Preserve it through any required sign-in step, and do not substitute an unrelated id query parameter from an example for another UI package.
Test an actual generated link while signed out and while signed in as the invited account. Include expired or already-used invitations in your test cases. The UI can present a friendly result, while the server must decide whether acceptance is allowed.
Organization UI does not scope business records automatically#
The companion uses Better Auth's organization state and native permissions. That does not automatically add an organization predicate to your Blog, CMS, Kanban, or application database queries.
For organization-owned data, resolve membership from the server session, verify access to the selected organization, and constrain the actual data read or write. A browser-selected organization ID is input to validate. It is not proof of membership. If BTST business plugins use generic authorization, connect that policy separately.
Test a member of organization A requesting a record from organization B directly. Also test a removed member with an old browser tab. A hidden navigation item is not evidence that either request is denied.
Add optional features deliberately#
The organization route factory includes teams and API-key page definitions, but the related runtime features require their own configuration. Do not enable teams or API-key controls merely because a route exists. Start with settings, membership, and a verified invitation flow, then add capabilities your application needs.
The companion documentation, released organization plugin, provider bridge, and invitation card are the source references for these UI-specific details.