Multi-account switching
A browser user regularly switches among personal, work, and customer accounts.
Better Auth · Function
multiSession
Better Auth's multi-session plugin keeps multiple account sessions active in one browser. It provides client operations for listing sessions, switching the active session, and revoking sessions.
How it works
The multi-session plugin lets one browser retain sessions for multiple accounts. Install the server and client plugins, then use the client methods to list sessions, activate one, or revoke one; the plugin defaults to five sessions per device.
Syntax
multiSession(); multiSessionClient(); authClient.multiSession.listDeviceSessions(); authClient.multiSession.setActive({ sessionToken }); authClient.multiSession.revoke({ sessionToken });Parameters
| Name | Type | Description |
|---|---|---|
sessionToken | string | The token identifying the session to activate. |
maximumSessions | number | The maximum number of sessions a user can have. |
Returns
listDeviceSessions returns the current user's active device sessions; setActive changes the active session; revoke removes a selected session.
Key points
- It supports simultaneous account sessions inside one browser, so users can change accounts without repeatedly authenticating.
- It fits account-switching interfaces where remaining signed in to several accounts is part of the workflow.
- Client-side management requires adding multiSessionClient() to the Better Auth client configuration.
- A login causes the plugin to add an extra browser cookie used for the additional session state.
- Use listDeviceSessions to retrieve the active sessions associated with the current device and user.
- Use setActive with a session token when the user chooses which account should become active.
Common mistakes
- Calling the existing sign-out flow removes every active session for that user, not only the currently active one.
- The default device limit is five sessions; configure maximumSessions when a different cap is required.
Example: Enable multi-session support
import { betterAuth } from "better-auth";
import { multiSession } from "better-auth/plugins";
import { createAuthClient } from "better-auth/client";
import { multiSessionClient } from "better-auth/client/plugins";
export const auth = betterAuth({
plugins: [multiSession()],
});
export const authClient = createAuthClient({
plugins: [multiSessionClient()],
});
const sessions = await authClient.multiSession.listDeviceSessions();
await authClient.multiSession.setActive({ sessionToken: sessions.data?.[0]?.token ?? "" });Register the server and client plugins, then retrieve device sessions and activate one by its session token.
When to use it
Tenant administration
An administration console lets an operator access several tenant accounts without repeated sign-ins.
Support workflows
A support tool needs to keep multiple customer contexts available in one browser.
Interview questions
QHow do you enable multi-session support?
The server registers multiSession(), while the browser client registers multiSessionClient(). The client plugin enables management of multiple active sessions in the browser.
Follow-up: What does the plugin use to preserve the additional sessions? It adds another browser cookie when a user logs in, and that cookie maintains the additional sessions.
QHow do you switch between accounts?
Call listDeviceSessions to obtain the active sessions for the current user. Then pass a selected session's token to setActive to make it the active session.
Follow-up: Which endpoint corresponds to listing sessions? The operation uses GET /multi-session/list-device-sessions.
QHow is the session limit configured?
The plugin accepts maximumSessions to limit how many sessions a user can have. If omitted, the documented default is five sessions per device.
Follow-up: What happens when the user signs out? The existing signOut method automatically revokes all active sessions for that user.
Related
multiSession()multiSessionClient()listDeviceSessionssetActiverevokesignOutmaximumSessions