Multi-session applications

One of the most powerful features that Clerk provides out of the box is multi-session applications.

A multi-session application is an application that allows multiple accounts to be signed in from the same browser at the same time. The user can switch from one account to another seamlessly. Each account is independent from the rest and has access to different resources.

Enable multi-session in your application

To enable multi-session in your application, you need to configure it in the Clerk Dashboard.

• Navigate to the Clerk Dashboard(opens in a new tab)
• Select your application, then select Sessions in the navigation sidebar.
• Toggle on Multi-session handling.
• Select Save changes.

Add multi-session support to your application

There are two main ways to add the multi-session feature to your application:

• Use Clerk components if you want to use Clerk's pre-built UI
• Build a custom flow if you want to rebuild the existing Clerk flow using the Clerk API.

Use Clerk components

The easiest way to add the multi-session feature to your application is by using Clerk's <UserButton /> component.

The following image demonstrates the <UserButton /> component with two accounts signed in. The user can switch between the two accounts, add a new account, or sign out from one or all accounts.

To learn how to use the <UserButton /> component in your application, check out the reference documentation.

Build a custom flow

If the UserButton /> component doesn't cover your needs, you can build a custom multi-session flow using Clerk's API.

To enable a multi-session instance, you need to handle the following scenarios:

• Switching between different accounts
• Adding new accounts
• Signing out from one account, while remaining signed in to the rest

Get the active session and user

import { useClerk } from "@clerk/clerk-react";
 
// Getting the active session and user
const { session: activeSession, user: activeUser } = useClerk();

// Getting the active session
const activeSession = window.Clerk.session;
 
// Getting the active user
const activeUser = window.Clerk.user;

Switch between sessions

import { useClerk } from "@clerk/clerk-react";
 
const { client, setActive } = useClerk();
 
// You can retrieve all the available sessions through the client
const availableSessions = client.sessions;
 
// Use setActive to set the active session.
setActive({ session: availableSessions[0].id });

// You can retrieve all the available sessions through the client
const availableSessions = window.Clerk.client.sessions;
 
// Use setActive to set the active session.
window.Clerk.setActive({ session: availableSessions[0].id });

Add a new session

To add a new session, simply link to your existing sign-in flow. New sign-ins will automatically add to the list of available sessions on the client. To create a sign-in flow, please check one of the following popular guides:

• Email and password
• Passwordless authentication
• Social login (OAuth)

For more information on how Clerk's sign-in flow works, check out the detailed sign-in guide.

Sign out active session

This version of sign out will deactivate the active session. The rest of the available sessions will remain intact.

import { useClerk } from "@clerk/clerk-react";
 
const { signOutOne } = useClerk();
 
// Use signOutOne to sign-out only from the active session.
await signOutOne();

// Use signOutOne to sign-out only from the active session.
await window.Clerk.signOutOne();

Sign out all sessions

This request will deactivate all sessions on the current client.

import { useClerk } from "@clerk/clerk-react";
 
const { signOut } = useClerk();
 
// Use signOut to sign-out all active sessions.
await signOut();

// Use signOut to sign-out all active sessions.
await window.Clerk.signOut();