Docs

You are viewing an archived version of the docs.Go to latest version

Session methods

These methods on the Clerk class help you manage the active session and/or organization.

setSession() (deprecated)

function setSession(
  session: Session | string | null,
  beforeEmit?: BeforeEmitCallback
): Promise<void>;

Caution

Clerk.setSession() is deprecated and will be removed in the Core 2 version of Clerk. Use setActive() instead.

Set the current session on this client to the provided session. The provided session can be either a complete Session object or simply its unique identifier.

Passing null as the session will result in the current session to be removed from the client.

If an active session already exists, it will be replaced with the new one. The change happens in three steps:

  1. The current Session object is set to undefined, which causes the control components to stop rendering their children as though Clerk is still initializing.
  2. The beforeEmit callback is executed. If a Promise is returned, Clerk waits for the Promise to resolve.
  3. The current Session is set to the passed session. This causes the control components to render their children again.

Properties

  • Name
    session
    Type
    Session | string | null
    Description

    A Session object or Session ID string to be set as the current session, or null to simply remove the active session, without setting a new one.

  • Name
    beforeEmit?
    Type
    (session: Session | null) => Promise<any>
    Description

    Callback that will trigger when the current session is set to undefined, before finally being set to the passed session. Usually used for navigation.

Returns

TypeDescription
Promise<void>The Promise will resolve after the passed session is set.

setActive()

A method used to set the active session and/or organization.

function setActive({
  session,
  organization,
  beforeEmit,
}: SetActiveParams): Promise<void>;

SetActiveParams

  • Name
    session?
    Type
    Session | string | null
    Description

    The session resource or session ID (string version) to be set as active. If null, the current session is deleted.

  • Name
    organization?
    Type
    Organization | string | null
    Description

    The organization resource or organization ID (string version) to be set as active in the current session. If null, the currently active organization is removed as active.

  • Name
    beforeEmit?
    Type
    (session?: Session | null) => void | Promise<any>
    Description

    Callback run just before the active session and/or organization is set to the passed object. Can be used to hook up for pre-navigation actions.

setActive() example

The setActive() method is most commonly used when building a custom flow for your application.

For example, during authentication, when a user signs in or signs up successfully, a new session is created. setActive() needs to be used to set the new session as the active session. See the implementation of this in the Custom authentication flow guide.

Another example is when a user switches organizations in a multi-organization application. setActive() needs to be used to set the new organization as the active organization. See the implementation of this in the Custom organization switcher guide.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on