Session options

Clerk provides session management options for fine-tuning user visits to your application, including options for session lifetime, multi-session handling, and session token customization.

Session lifetime

Choosing a session lifetime is a trade-off between security and user experience. Longer sessions keep users signed in, while shorter sessions limit how long a session can be used.

Configure session lifetimes on the Sessions⁠ page in the Clerk Dashboard. Web browser settings apply to all sessions by default. On instances with separate native session settings, you can give native sessions their own lifetime.

Web browser sessions

Web browser sessions support Inactivity timeout and Maximum lifetime. At least one of these settings must remain enabled.

Inactivity timeout

Inactivity timeout is the duration after which a session expires if the user hasn't been active on your site. A user is considered inactive when the application is closed or stops refreshing the token.

By default, this setting is disabled. To enable it and set a custom inactivity timeout:

1. In the Clerk Dashboard, navigate to the Sessions⁠ page.
2. Toggle on Inactivity timeout.
3. Set your desired duration.

Maximum lifetime

Maximum lifetime is the duration after which a session expires regardless of the user's activity on your site.

This setting defaults to 7 days on newly created instances. Setting a custom maximum lifetime requires a paid plan for production use, but it's available in development mode so that you can try out what works for you. To change it:

1. In the Clerk Dashboard, navigate to the Sessions⁠ page.
2. Toggle on Maximum lifetime.
3. Set your desired duration.

Browser limitations on cookies

Browser cookies can be cleared or expire before a session reaches its configured lifetime. As a result, you can't guarantee that a browser session will last for its full configured lifetime.

User behaviors

If a user clears their cookies, Clerk's session cookie is lost. The same happens when a user closes all incognito windows after signing in there. In either case, the user must sign in again.

Google Chrome

Cookies set in Google Chrome have a Max-Age upper limit of 400 days⁠. Users who use Google Chrome will be signed out within 400 days, even if the session lifetime is set to a longer duration. There is no workaround for this.

This is per the HTTP Working Group Specification⁠ which is likely to be implemented by other browsers in the future.

Native sessions

Native sessions are sessions created by these apps:

• iOS and Android apps, including Expo apps on iOS and Android.
• Electron apps.
• Chrome extensions on production instances only. In development, their sessions use the web browser settings. If a Chrome extension syncs authentication with a web app, the shared session uses the web browser settings.

By default, native sessions use the web browser settings for both Inactivity timeout and Maximum lifetime. If your instance has separate native session settings, you can choose a different policy for new native sessions.

Configure a separate native lifetime

On a paid plan, you can set a custom maximum lifetime for native sessions between 5 minutes and 10 years in production. It's also available in development mode. When native sessions have their own maximum lifetime, web browser settings, including inactivity timeout, don't apply to them. A long native lifetime doesn't extend the lifetime of session tokens. SDKs continue refreshing these short-lived tokens.

To set a maximum lifetime for new native sessions:

1. In the Clerk Dashboard, navigate to the Sessions⁠ page.
2. Under Native sessions, select Custom maximum lifetime and set a duration.
3. Select Save.

To make native sessions follow the web browser settings again, select Same as web, then select Save. Changing either the web or native settings preserves the other platform's settings. If your plan is downgraded, native sessions return to following the web browser settings, and the web maximum lifetime returns to 7 days.

Changes to existing sessions

Changing a web or native session lifetime setting only affects sessions created after you save the change. Existing sessions keep the maximum lifetime and inactivity timeout they were created with, so lowering a duration doesn't shorten or end sessions that are already active. This also applies to settings that are reset when your plan is downgraded.

To end existing sessions, revoke them. In the Clerk Dashboard, open a user from the Users⁠ page and select Revoke device or Revoke all devices in the Devices section. To revoke sessions programmatically, use the Backend SDK's revokeSession() method.

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.

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

1. In the Clerk Dashboard, navigate to the Sessions⁠ page.
2. Toggle on Multi-session handling.
3. Select Save.

Add multi-session support to your app

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

• Use the <UserButton /> component if you want to use a prebuilt UI.
• Build a custom flow if you want to rebuild the existing Clerk flow using the Clerk API.

It's highly recommended to wrap your application with the following <MultisessionAppSupport /> component. The fragment's key is set to the session ID. Every time the session ID changes, the key changes, forcing React to recreate the entire component tree under the fragment and guaranteeing a full rerendering cycle.

function MultisessionAppSupport({ children }: { children: React.ReactNode }) {
  const { session } = useSession()

  return <React.Fragment key={session ? session.id : 'no-users'}>{children}</React.Fragment>
}

The following example demonstrates adding multi-session support to a Next.js App Router application. It requires creating the <MultisessionAppSupport /> as a client component, and then using it in the app/layout.tsx file to wrap the entire application. This ensures the layout.tsx remains a server component.

import React from 'react'
import { ClerkProvider } from '@clerk/nextjs'
import { MultisessionAppSupport } from './components/MultisessionAppSupport'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider afterMultiSessionSingleSignOutUrl="/">
          <MultisessionAppSupport>{children}</MultisessionAppSupport>
        </ClerkProvider>
      </body>
    </html>
  )
}

'use client'

import React from 'react'
import { useSession } from '@clerk/nextjs'

export default function MultisessionAppSupport({ children }: { children: React.ReactNode }) {
  const { session } = useSession()

  return <React.Fragment key={session ? session.id : 'no-users'}>{children}</React.Fragment>
}

Sign out behavior

By default, signing out from a currently active account in a multi-session app will navigate to the sign-in page's /choose route.

If a sign-in URL is not set, signing out will navigate to Clerk's Account Portal /sign-in/choose page, allowing the user to choose which account to switch into.

If a sign-in URL is set, either through the signInUrl prop on <ClerkProvider> or the CLERK_SIGN_IN_URL environment variable, signing out will navigate to that URL's /choose route. For example, if signInUrl or CLERK_SIGN_IN_URL is set to https://example.com/sign-in, signing out of a multi-session app will navigate to https://example.com/sign-in/choose.

Customize session token

Session tokens are JWTs that contain a set of default claims required by Clerk. You can customize these tokens by providing additional claims of your own.

To learn how to customize session tokens, see the dedicated guide.