Switch Accounts with BTST Better Auth UI

BTST Better Auth UI can show an account switcher for several authenticated accounts in the same browser. Connect Better Auth's multi-session server plugin, its client plugin, and the companion's multi-session option, then make account changes refresh the application's private data.

This guide targets better-auth@1.6.16, @btst/better-auth-ui@2.0.1, and @btst/stack@3.1.2. It assumes that your existing auth integration works. Use the companion documentation to establish its routes, provider, and user menu before adding switching.

Choose account switching for the right job#

An account switch changes the active authenticated user. An organization switch usually changes the active workspace while retaining that user. A list of one user's sessions on other devices is a third concern, covered by the session-management guide.

Use multi-session when people intentionally sign in to separate identities in one browser. It does not merge those identities, grant impersonation permission, or make one user's private resources visible to another. Keep server-side ownership and membership checks on every protected operation.

Add the server and client plugins#

Add this plugin to your existing betterAuth(...) configuration's plugins array:

import { multiSession } from "better-auth/plugins/multi-session";

export const accountSwitching = multiSession({
  maximumSessions: 3,
});

In your browser auth-client module, add the matching plugin to the existing createAuthClient(...) call's plugins array:

import { multiSessionClient } from "better-auth/client/plugins";

export const accountSwitchingClient = multiSessionClient();

Retain every existing server and client plugin. Do not create a second auth client just for the menu. The server option controls the multi-session cookie set on that browser; it is not a global limit on how many devices a user may sign in from. Exercise the capacity boundary in your own flow rather than assuming it blocks every additional authentication attempt.

Enable switching in the companion#

This helper makes an auth override object using your existing browser client and session-change callback:

import type { AuthPluginOverrides } from "@btst/better-auth-ui/client";

export function multiAccountUI(
  authClient: AuthPluginOverrides["authClient"],
  onSessionChange: NonNullable<AuthPluginOverrides["onSessionChange"]>,
): AuthPluginOverrides {
  return {
    authClient,
    multiSession: true,
    onSessionChange,
  };
}

Merge the result into overrides.auth; keep existing redirects, enabled auth methods, and page customizations. Use your already configured UserButton under the companion's provider integration. With multi-session enabled, the released menu lists other available users and offers an “Add account” link to sign in again. Selecting an account calls the active-session mutation and then the session-change callback.

Switching must update more than the avatar. For Next.js, retain the integration's router.refresh() callback. In React Router, revalidate the relevant loaders; in TanStack Start, invalidate the router. Also clear or invalidate application-owned queries containing private user data, and scope those queries to the active user where appropriate. A framework refresh alone does not guarantee that every custom client cache has changed owner.

Verify the privacy boundary#

Use two disposable users with visibly different private records. Sign in as the first, add the second, then switch both ways. After each switch, verify the current server session, protected page data, API reads, and attempted writes. Data belonging only to the previous user must not remain available because a query reused its old cache entry.

Test an account from a different browser profile: knowing a user ID or possessing an unrelated active session must not make it appear as switchable. The pinned server uses signed device-session cookies when accepting an active-session change. Keep session tokens out of URLs, logs, analytics, and persistent JavaScript storage.

Test expired and revoked sessions as well. A stale menu entry should not become authorization; the server must reject a switch to an unavailable session. The UI should recover by refreshing its session list and displaying a useful error.

Make sign-out behavior explicit#

Switching, revoking one device session, and signing out have different effects. In the pinned release, the multi-session sign-out hook expires the multi-session cookies presented by that browser and removes the corresponding verified sessions. Do not describe the default sign-out action as “sign out of this account only.”

Check another browser's session separately. The browser-local multi-session cookie set is not an inventory of all sessions on all devices. Use the appropriate session-management endpoints when your product offers “sign out other devices.” Verify this behavior after upgrading auth dependencies.

For multiple workspaces under one identity, continue with organization settings and invitations instead. For installation and package compatibility, use the dependency guide.

Sources: Better Auth multi-session setup, its pinned server implementation, and the released companion's user menu, provider bridge, and sign-out component.