Build a custom multi-session flow

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.

This guide provides you with the necessary information to build a custom multi-session flow using Clerk's API.

To implement the multi-session feature to your application, 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
• Signing out from all accounts

Enable multi-session in your application

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

1. Navigate to the Clerk Dashboard(opens in a new tab) and select your application.
2. In the navigation sidebar, select Sessions.
3. Toggle on Multi-session handling.
4. Select Save changes.

Get the active session and user

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

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

Switch between sessions

import { useClerk } from "@clerk/clerk-react";
 
const { client, setActive } = useClerk();
 
// You can get 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 get 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 sign-in (OAuth)

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

Sign out all sessions

Use signOut() to deactivate all sessions on the current client.

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

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

Sign out active session

Use signOut() to deactivate a specific session by passing the session ID.

import { useClerk } from "@clerk/clerk-react";
 
// Get the signOut method and the active session
const { signOut, session } = useClerk();
 
// Use signOut to sign-out the active session
await signOut(session.id);

// Get the active session
const activeSession = window.Clerk.session;
 
// Use signOut to sign-out the active session
await window.Clerk.signOut(activeSession.id);

Last updated on March 12, 2024