Search…
Multi-session applications
Learn how to configure and work with multi-session applications

Overview

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.
Clerk's User button
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 our detailed guide.

Before you start

Configuration

The first thing you need to do is to enable the multi-session feature in your Clerk instance.
From the Clerk Dashboard, select your instance, and navigate to Settings > User Management > User sessions.
Choose Multi-session.
Enabling multi-session in your instance
That's all you have to do! Now you have a multi-session application!

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.
Clerk React
ClerkJS
1
import { UserButton } from "@clerk/clerk-react";
2
3
const Header = () => {
4
return (
5
<header>
6
<h1>My application</h1>
7
<UserButton />
8
</header>
9
);
10
};
Copied!
1
<html>
2
<body>
3
<header>
4
<h1>My application</h1>
5
<div id="user-button"></div>
6
</header>
7
8
<script>
9
const el = document.getElementById("user-button");
10
// Mount the pre-built Clerk UserButton component
11
// in an HTMLElement on your page.
12
window.Clerk.mountUserButton(el);
13
</script>
14
</body>
15
</html>
Copied!
Note that you don't need to pass any special options to the UserButton component. For more details on all available options, including customization options, please visit the <UserButton /> guide.

Custom flow

In case you want more customizability, and you prefer full control over your UI, you can use Clerk's SDKs.

Active session/user

Clerk React
ClerkJS
1
import { useClerk } from "@clerk/clerk-react";
2
3
// Getting the active session and user
4
const { session: activeSession, user: activeUser } = useClerk();
Copied!
1
// Getting the active session
2
const activeSession = window.Clerk.session;
3
4
// Getting the active user
5
const activeUser = window.Clerk.user;
Copied!

Switching sessions

Clerk React
ClerkJS
1
import { useClerk } from "@clerk/clerk-react";
2
3
const { client, setSession } = useClerk();
4
5
// You can retrieve all the available sessions through the client
6
const availableSessions = client.sessions;
7
8
// Use setSession to set the active session.
9
setSession(availableSessions[0].id);
Copied!
1
// You can retrieve all the available sessions through the client
2
const availableSessions = window.Clerk.client.sessions;
3
4
// Use setSession to set the active session.
5
window.Clerk.setSession(availableSessions[0].id);
Copied!

Adding sessions

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, checkout our 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.
Clerk React
ClerkJS
1
import { useClerk } from "@clerk/clerk-react";
2
3
const { signOutOne } = useClerk();
4
5
// Use signOutOne to sign-out only from the active session.
6
await signOutOne();
Copied!
1
// Use signOutOne to sign-out only from the active session.
2
await window.Clerk.signOutOne();
Copied!

Sign out of all sessions

This request will deactivate all sessions on the current client.
Clerk React
ClerkJS
1
import { useClerk } from "@clerk/clerk-react";
2
3
const { signOut } = useClerk();
4
5
// Use signOut to sign-out all active sessions.
6
await signOut();
Copied!
1
// Use signOut to sign-out all active sessions.
2
await window.Clerk.signOut();
Copied!
Last modified 1mo ago