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. It's most clearly explained by the default <UserButton /> below.

Note that you can switch which account is active, add additional accounts, and manage each account independently. 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

There are two main ways to handle all the above: using Clerk Components or using a custom flow.

Looking for more information on session management? Check out the detailed guide.

Before you start

You need to create a Clerk Application in your Clerk Dashboard. For more information, check out the Set up your application guide.
You need to install the correct SDK for your application. You can find steps on how to do so through Clerk's quickstart guides.

Configuration

To enable the multi-session feature in your Clerk instance, go to the Clerk Dashboard and navigate to Sessions. Toggle on Multi-session handling and don't forget to select Apply changes.

The Sessions page in the Clerk Dashboard. A red arrow points to the active Sessions tab. On this page, a red arrow points to the Multi-session handling toggle, which is toggled on. There is also a red arrow pointing to the 'Apply changes' button.

Using Clerk Components

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

This component has buttons add a new account, switch between accounts, and sign out from one or all accounts.


import { UserButton } from "@clerk/clerk-react";
 
const Header = () => {
  return (
    <header>
      <h1>My application</h1>
      <UserButton />
    </header>
  );
};


<html>
<body>
    <header>
        <h1>My application</h1>
        <div id="user-button"></div>
    </header>
    
    <script>
        const el = document.getElementById("user-button");
        // Mount the pre-built Clerk UserButton component
        // in an HTMLElement on your page. 
        window.Clerk.mountUserButton(el);
    </script>
</body>
</html>

Custom flow

In case the pre-built user button doesn't cover your needs and you prefer a custom multisession flow, you can easily make use of Clerk's SDKs.

Active session/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;

Switching 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 });

Adding 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:

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();