`Clerk` class

Example
Properties
Methods
Components

Available in other SDKs

The Clerk class serves as the central interface for working with Clerk's authentication and user management functionality in your application. As a top-level class in the Clerk SDK, it provides access to key methods and properties for managing users, sessions, API keys, billing, organizations, and more.

Example

The following example uses the useClerk() hook to access the clerk object. The clerk object is used to call the openSignIn() method to open the sign-in modal.

src/pages/Example.tsx

import { useClerk } from '@clerk/react'

export default function Example() {
  const clerk = useClerk()

  return <button onClick={() => clerk.openSignIn({})}>Sign in</button>
}

Properties

Name
apiKeys
Type
APIKeys
Description
The APIKeys object used for managing API keys.
Name
billing
Type
Billing
Description
The Billing object used for managing billing.
Name
client
Type
Client
Description
The Client object for the current window.
Name
domain
Type
string
Description
The current Clerk app's domain. Prefixed with clerk. on production if not already prefixed. Returns "" when ran on the server.
Name
instanceType
Type
'production' | 'development'
Description
Indicates if the Clerk instance is running in production or development mode.
Name
isSatellite
Type
boolean
Description
A boolean that indicates if the instance is a satellite app.
Name
isStandardBrowser
Type
boolean | undefined
Description
Indicates if the instance is being loaded in a standard browser environment. Set to false on native platforms where cookies cannot be set. When undefined, Clerk assumes a standard browser.
Name
isSignedIn
Type
boolean
Description
A boolean that indicates if the user is signed in.
Name
loaded
Type
boolean
Description
A boolean that indicates if the Clerk object is ready for use. Set to false when the status is 'loading' or 'error'. Set to true when the status is either 'ready' or 'degraded'.
Name
organization
Type
Organization | null | undefined
Description
A shortcut to the last active Session.user.organizationMemberships which holds an instance of a Organization object. If the session is null or undefined, the user field will match.
Name
proxyUrl
Type
string | undefined
Description
Your Clerk app's proxy URL. Required for applications that run behind a reverse proxy. Can be either a relative path (/__clerk) or a full URL (https://<your-domain>/__clerk).
Name
publishableKey
Type
string | undefined
Description
Your Clerk Publishable Key.
Name
sdkMetadata
Type
{ name: string; version: string; environment?: string } | undefined
Description
Contains information about the SDK that the host application is using (e.g. { name: '@clerk/nextjs', version: '1.0.0' }). You don't need to set this value yourself unless you're developing an SDK.
Name
session
Type
Session | null | undefined
Description
The currently active Session, which is guaranteed to be one of the sessions in Client.sessions. If there is no active session, this field will be null. If the session is loading, this field will be undefined.
Name
status
Type
'degraded' | 'error' | 'loading' | 'ready'
Description
The status of the Clerk instance. Possible values are:

'degraded': Set when Clerk is partially operational.

'error': Set when hotloading clerk-js failed or Clerk.load() failed.

'loading': Set during initialization.

'ready': Set when Clerk is fully operational.
Name
telemetry?
Type
{ disabled: boolean, debug: boolean }
Description
Telemetry configuration.
Name
user
Type
User | null | undefined
Description
A shortcut to Session.user which holds the currently active User object. If the session is null or undefined, the user field will match.
Name
version
Type
string | undefined
Description
The Clerk SDK version.

Methods

`addListener()`

Registers a listener that triggers a callback whenever a change in the Client, Session, or User object occurs. This method is primarily used to build frontend SDKs like @clerk/react. Returns an UnsubscribeCallback function that can be used to remove the listener from the Clerk object.

function addListener(
  callback: (emission: Resources) => void,
  options?: ListenerOptions,
): UnsubscribeCallback

Parameters

Name
callback
Type
(emission: Resources) => void
Description
The function to call when Clerk resources change.
Name
options?
Type
ListenerOptions
Description
Optional configuration. ListenerOptions is an object that accepts the following properties:

skipInitialEmit (boolean): if true, the callback is not called immediately after registration. Defaults to false.

`Resources`

Name
client
Type
Client
Description
Name
session
Type
Session | null | undefined
Description
Name
user
Type
User | null | undefined
Description
Name
organization
Type
Organization | null | undefined
Description

Note

Note the following about User and Session:

When there is an active session, user === session.user.
When there is no active session, User and Session will both be null.

`authenticateWithMetamask()`

Starts a sign-in flow that uses the MetaMask browser extension to authenticate the user using their Ethereum wallet address.

function authenticateWithMetamask({
  redirectUrl,
  signUpContinueUrl,
  customNavigate,
}?: AuthenticateWithMetamaskParams): Promise<void>

`AuthenticateWithMetamaskParams`

Name
redirectUrl?
Type
string | undefined
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string | undefined
Description
The URL to navigate to if the sign-up process is missing user information.
Name
customNavigate?
Type
((to: string) => Promise<unknown> | unknown) | undefined
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

`authenticateWithCoinbaseWallet()`

Starts a sign-in flow that uses the Coinbase Wallet to authenticate the user using their Web3 wallet address.

function authenticateWithCoinbaseWallet({
  redirectUrl,
  signUpContinueUrl,
  customNavigate,
}?: AuthenticateWithCoinbaseWalletParams): Promise<void>

`AuthenticateWithCoinbaseWalletParams`

Name
redirectUrl?
Type
string | undefined
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string | undefined
Description
The full URL or path to navigate to if the sign-up process is missing user information.
Name
customNavigate?
Type
((to: string) => Promise<unknown> | unknown) | undefined
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

`authenticateWithOKXWallet()`

Starts a sign-in flow that uses the OKX Wallet to authenticate the user using their Web3 wallet address.

function authenticateWithOKXWallet(props?: AuthenticateWithOKXWalletParams): Promise<void>

`AuthenticateWithOKXWalletParams`

Name
redirectUrl?
Type
string | undefined
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string | undefined
Description
The full URL or path to navigate to if the sign-up process is missing user information.
Name
customNavigate?
Type
((to: string) => Promise<unknown> | unknown) | undefined
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.

`authenticateWithBase()`

Starts a sign-in flow that uses Base to authenticate the user using their Web3 wallet address.

function authenticateWithBase(props?: AuthenticateWithBaseParams): Promise<void>

`AuthenticateWithBaseParams`

Name
redirectUrl?
Type
string | undefined
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string | undefined
Description
The full URL or path to navigate to if the sign-up process is missing user information.
Name
customNavigate?
Type
((to: string) => Promise<unknown> | unknown) | undefined
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.

`authenticateWithSolana()`

Starts a sign-in flow that uses Solana to authenticate the user using their Solana wallet address. This method prompts the user to connect their Solana wallet and sign a message to verify ownership of the wallet address. The walletName parameter specifies which Solana wallet provider to use for the authentication process, which is required to initiate the connection and signature request.

function authenticateWithSolana(props?: AuthenticateWithSolanaParams): Promise<void>

`AuthenticateWithSolanaParams`

Name
walletName
Type
string
Description
The name of the Solana wallet provider to use for the authentication process.
Name
redirectUrl?
Type
string | undefined
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string | undefined
Description
The full URL or path to navigate to if the sign-up process is missing user information.
Name
customNavigate?
Type
((to: string) => Promise<unknown> | unknown) | undefined
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.

`authenticateWithWeb3()`

function authenticateWithWeb3({
  redirectUrl,
  signUpContinueUrl,
  customNavigate,
  strategy,
}: ClerkAuthenticateWithWeb3Params): Promise<void>

`ClerkAuthenticateWithWeb3Params`

Name
redirectUrl?
Type
string | undefined
Description
The full URL or path to navigate to after a successful sign in or sign up.
Name
signUpContinueUrl?
Type
string | undefined
Description
The full URL or path to navigate to if the sign-up process is missing user information.
Name
customNavigate?
Type
((to: string) => Promise<unknown> | unknown) | undefined
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.
Name
strategy
Type
Web3Strategy
Description
The Web3 verification strategy.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
secondFactorUrl?
Type
string
Description
The full URL or path to navigate to during sign in, if multi-factor authentication is enabled.
Name
walletName?
Type
string
Description
The name of the wallet provider to use for the authentication process. This parameter is required when using web3_solana_signature as the strategy.

`authenticateWithGoogleOneTap()`

Authenticates the user using a Google token from Google Identity Services (e.g. Google One Tap). Returns the resulting SignIn or SignUp resource; use handleGoogleOneTapCallback() to complete the flow after redirect.

function authenticateWithGoogleOneTap(
  params: AuthenticateWithGoogleOneTapParams,
): Promise<SignIn | SignUp>

`AuthenticateWithGoogleOneTapParams`

Name
token
Type
string
Description
The Google credential token from the Google Identity Services response.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.

`buildCreateOrganizationUrl()`

Returns the configured URL where <CreateOrganization /> is mounted or a custom create-organization page is rendered.

function buildCreateOrganizationUrl(): string

`buildHomeUrl()`

Returns the URL you've configured in the Clerk Dashboard.

function buildHomeUrl(): string

`buildOrganizationProfileUrl()`

Returns the configured URL where <OrganizationProfile /> is mounted or a custom organization-profile page is rendered.

function buildOrganizationProfileUrl(): string

Returns the configured URL where <SignIn /> is mounted or a custom sign-in page is rendered.

function buildSignInUrl(options?: RedirectOptions): string

Parameters

Name
options
Type
RedirectOptions | undefined
Description
Options used to control the redirect in the constructed URL.

Returns the configured URL where <SignUp /> is mounted or a custom sign-up page is rendered.

function buildSignUpUrl(options?: RedirectOptions): string

Parameters

Name
options
Type
RedirectOptions | undefined
Description
Options used to control the redirect in the constructed URL.

`buildUrlWithAuth()`

Decorates the provided URL with the auth token for development instances.

function buildUrlWithAuth(to: string): string

Parameters

Name
to
Type
string
Description
The route to create a URL towards.

`buildUserProfileUrl()`

Returns the URL where <UserProfile /> is mounted or a custom user-profile page is rendered.

function buildUserProfileUrl(): string

`buildTasksUrl()`

Returns the configured URL where session tasks are mounted.

function buildTasksUrl(): string

Returns the configured after-sign-in URL of the instance.

function buildAfterSignInUrl(options?: { params?: URLSearchParams }): string

Parameters

Name
options?.params
Type
URLSearchParams | undefined
Description
Optional query parameters to append to the URL.

Returns the configured after-sign-up URL of the instance.

function buildAfterSignUpUrl(options?: { params?: URLSearchParams }): string

Parameters

Name
options?.params
Type
URLSearchParams | undefined
Description
Optional query parameters to append to the URL.

`buildAfterSignOutUrl()`

Returns the configured after-sign-out URL of the instance.

function buildAfterSignOutUrl(): string

`buildNewSubscriptionRedirectUrl()`

Returns the configured URL to redirect to after a new subscription is created.

function buildNewSubscriptionRedirectUrl(): string

`buildAfterMultiSessionSingleSignOutUrl()`

Returns the configured URL to redirect to after a user signs out of a single session in a multi-session application.

function buildAfterMultiSessionSingleSignOutUrl(): string

`buildWaitlistUrl()`

Returns the configured URL where <Waitlist /> is mounted or a custom waitlist page is rendered.

function buildWaitlistUrl(options?: { initialValues?: Record<string, string> }): string

Parameters

Name
options?.initialValues
Type
Record<string, string> | undefined
Description
Optional initial values to prefill the waitlist form (e.g. email).

`constructor()`

Create an instance of the Clerk class with dedicated options.

This method is only available when importing Clerk from @clerk/clerk-js, rather than using a Window script.

class Clerk {
  constructor(key: string, options?: DomainOrProxyUrl)
}

Parameters

Name
key
Type
string
Description
Your Clerk Publishable Key.
Name
options?
Type
DomainOrProxyUrl | undefined
Description
The domain or proxy URL used to connect to Clerk.

`DomainOrProxyUrl`

Only one of the two properties are allowed to be set at a time.

Name
proxyUrl?
Type
never | string | ((url: URL) => string)
Description
The proxy URL used to connect to Clerk. If a function, will be called with a URL made from window.location.href.
Name
domain?
Type
never | string | ((url: URL) => string)
Description
The domain used to connect to Clerk. If a function, will be called with a URL made from window.location.href.

`createOrganization()`

Creates an Organization programmatically. Returns an Organization object.

Note

For React-based apps, consider using the <CreateOrganization /> component.

function createOrganization({ name, slug }: CreateOrganizationParams): Promise<Organization>

Parameters

Name
name
Type
string
Description
The name of the Organization to be created.
Name
slug?
Type
string
Description
The optional slug of the Organization to be created.

`getOrganization()`

Retrieves information for a specific Organization.

function getOrganization(organizationId: string): Promise<Organization | undefined>

Parameters

Name
organizationId
Type
string
Description
The ID of the Organization to be found.

`handleEmailLinkVerification()`

Handles the completion of an email link verification flow by processing the verification results from the redirect URL query parameters. This method should be called after the user is redirected back from visiting the verification link in their email.

function handleEmailLinkVerification(
  params: handleEmailLinkVerificationParams,
  customNavigate?: ((to: string) => Promise<unknown>) | undefined,
): Promise<unknown>

The handleEmailLinkVerification() method finalizes an email verification flow that begins when a user initiates email verification and ends when they visit the verification link.

Email verification can be completed on any device - not necessarily the one where it was initiated. For example, a user could start verification on desktop but click the email link on mobile.

When a user visits the verification link, they are redirected to the URL specified during flow initialization. Clerk appends these query parameters to the URL:

__clerk_status: The verification outcome:
- verified: Verification succeeded.
- failed: Verification failed.
- expired: Link expired.
- client_mismatch: Device/browser mismatch (only if same device verification is enabled).
__clerk_created_session: ID of any new session created. Since verification can happen on a different device, this session may not appear in Client.sessions.

The method handles the verification outcome as follows:

On successful verification, it:
- Determines if sign-in/sign-up is complete
- Redirects accordingly using the provided URLs (both optional):
  - redirectUrlComplete: URL for completed sign-in/sign-up.
  - redirectUrl: URL if there are further requirements for the sign-in/sign-up attempt, such as MFA.
- Executes an optional callback if verification happened on another device.
On verification failure:
- Throws an EmailLinkError.
- Error code indicates if link expired or verification failed.

Take a look at the function parameters below for more usage details.

Parameters

Name
params
Type
handleEmailLinkVerificationParams
Description
Allows you to define the URLs where the user should be redirected to on successful verification or pending/completed sign-up or sign-in attempts. If the email link is successfully verified on another device, there's a callback function parameter that allows custom code execution.
Name
customNavigate?
Type
(to: string) => Promise<unknown>
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

`handleEmailLinkVerificationParams`

Name
redirectUrlComplete?
Type
string | undefined
Description
The full URL to navigate to after successful email link verification on completed sign-up or sign-in on the same device.
Name
redirectUrl?
Type
string | undefined
Description
The full URL to navigate to after successful email link verification on the same device, but without completing sign-in or sign-up.
Name
onVerifiedOnOtherDevice?
Type
() => void
Description
Callback function to be executed after successful email link verification on another device.

`handleRedirectCallback()`

Completes a custom OAuth or SAML redirect flow that was started by calling SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params).

function handleRedirectCallback(
  params: HandleOAuthCallbackParams | HandleSamlCallbackParams,
  customNavigate?: ((to: string) => Promise<unknown>) | undefined,
): Promise<unknown>

Parameters

Name
params
Type
HandleOAuthCallbackParams | HandleSamlCallbackParams
Description
Additional props that define where the user will be redirected to at the end of a successful OAuth or SAML flow.
Name
customNavigate
Type
(to: string) => Promise<unknown>
Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

`HandleOAuthCallbackParams`

Name
continueSignUpUrl?
Type
string | undefined | null
Description
The full URL or path to navigate to if the sign up requires additional information.
Name
signInUrl?
Type
string
Description
The full URL or path where the <SignIn /> component is mounted.
Name
signUpUrl?
Type
string
Description
The full URL or path where the <SignUp /> component is mounted.
Name
signInFallbackRedirectUrl?
Type
string
Description
The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.
Name
signUpFallbackRedirectUrl?
Type
string
Description
The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.
Name
signInForceRedirectUrl?
Type
string
Description
If provided, this URL will always be redirected to after the user signs in. It's recommended to use the environment variable instead.
Name
signUpForceRedirectUrl?
Type
string
Description
If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.
Name
firstFactorUrl?
Type
string | undefined
Description
The full URL or path to navigate to during sign in, if first factor verification is required.
Name
secondFactorUrl?
Type
string | undefined
Description
The full URL or path to navigate to during sign in, if multi-factor authentication is enabled.
Name
resetPasswordUrl?
Type
string
Description
The full URL or path to navigate to during sign in, if the user is required to reset their password.
Name
transferable?
Type
boolean
Description
A boolean that indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to true. When set to false, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist.
Name
verifyEmailAddressUrl?
Type
string | undefined | null
Description
The full URL or path to navigate to after requesting email verification.
Name
verifyPhoneNumberUrl?
Type
string | undefined | null
Description
The full URL or path to navigate to after requesting phone verification.

See the custom flow guide for implementation details on how to implement a custom OAuth flow.

`handleGoogleOneTapCallback()`

Completes a Google One Tap redirect flow started by authenticateWithGoogleOneTap(). Call this when the user returns from the Google One Tap redirect.

function handleGoogleOneTapCallback(
  signInOrUp: SignIn | SignUp,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
): Promise<unknown>

Parameters

Name
signInOrUp
Type
SignIn | SignUp
Description
The resource returned from the initial authenticateWithGoogleOneTap() call (before redirect).
Name
params
Type
HandleOAuthCallbackParams
Description
Redirect URLs and options for the callback (e.g. signInUrl, signUpUrl, signInForceRedirectUrl).
Name
customNavigate?
Type
(to: string) => Promise<unknown>
Description
A function that overrides Clerk's default navigation behavior.

`handleUnauthenticated()`

Handles a 401 response from Frontend API by refreshing the client and session object accordingly.

function handleUnauthenticated(opts?: { broadcast: boolean }): Promise<unknown>

`joinWaitlist()`

Create a new waitlist entry programmatically. Requires that you set your app's sign-up mode to Waitlist in the Clerk Dashboard.

function joinWaitlist({ emailAddress }: JoinWaitlistParams): Promise<Waitlist>

Parameters

Name
emailAddress
Type
string
Description
The email address of the user you want to add in the waitlist.

`load()`

Initializes the Clerk object and loads all necessary environment configuration and instance settings from the Frontend API.

You must call this method before using the Clerk object in your code. Refer to the quickstart guide for more information.

function load(options?: ClerkOptions): Promise<void>

`ClerkOptions`

The load() method accepts an optional object that accepts the following props. All props are optional.

Name
appearance
Type
Appearance | undefined
Description
Optional object to style your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
Name
localization
Type
Localization | undefined
Description
Optional object to localize your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
Name
routerPush?
Type
(to: string) => Promise<unknown> | void
Description
A function which takes the destination path as an argument and performs a "push" navigation.
Name
routerReplace?
Type
(to: string) => Promise<unknown> | void
Description
A function which takes the destination path as an argument and performs a "replace" navigation.
Name
polling
Type
boolean | undefined
Description
Dictates if we should poll against Clerk's backend every 5 minutes. Defaults to true.
Name
selectInitialSession
Type
((client: [Client][client-ref]) => Session | null) | undefined
Description
An optional function which allows you to control which active session is the initial session to base a user's state off of. Defaults to the first session in the client's sessions array.
Name
standardBrowser
Type
boolean | undefined
Description
Controls if ClerkJS will load with the standard browser set up using Clerk cookies. Defaults to true.
Name
supportEmail
Type
string | undefined
Description
Optional support email for display in authentication screens.
Name
touchSession
Type
boolean | undefined
Description
Indicates whether the session should be "touched" when user interactions occur, used to record these interactions. Defaults to true.
Name
signInUrl
Type
string | undefined
Description
The default URL to use to direct to when the user signs in. It's recommended to use the environment variable instead.
Name
signUpUrl
Type
string | undefined
Description
The default URL to use to direct to when the user signs up. It's recommended to use the environment variable instead.
Name
signInForceRedirectUrl?
Type
string
Description
If provided, this URL will always be redirected to after the user signs in. It's recommended to use the environment variable instead.
Name
signUpForceRedirectUrl?
Type
string
Description
If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.
Name
signInFallbackRedirectUrl?
Type
string
Description
The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.
Name
signUpFallbackRedirectUrl?
Type
string
Description
The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.
Name
afterSignOutUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-out.
Name
allowedRedirectOrigins?
Type
Array<string | RegExp>
Description
An optional array of domains to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.
Name
allowedRedirectProtocols?
Type
Array<string>
Description
An optional array of protocols to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.
Name
isSatellite
Type
boolean | ((url: URL) => boolean) | undefined
Description
Clerk flag for satellite apps. Experimental.
Name
telemetry?
Type
false | { disabled?: boolean; debug?: boolean } | undefined
Description
Controls whether or not Clerk will collect telemetry data.

`navigate()`

Helper method which will use the custom push navigation function of your application to navigate to the provided URL or relative path.

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function navigate(to: string | undefined, options?: NavigateOptions): Promise<unknown> | void

Parameters

Name
to
Type
string | undefined
Description
The route to navigate to.
Name
options?
Type
NavigateOptions
Description
Optional configuration. NavigateOptions is an object that accepts the following properties:

replace? (boolean): If true, replace the current history entry instead of pushing a new one.

metadata? (RouterMetadata): Optional router metadata.

`on()`

Registers an event handler for a specific Clerk event.

type OnEventListener = <E extends ClerkEvent>(
  event: E,
  handler: EventHandler<E>,
  opt?: {
    notify: boolean
  },
) => void

Parameters

Name
event
Type
E
Description
The event to listen to. Currently, the only supported event is status.
Name
handler
Type
EventHandler<E>
Description
The handler to call when the event is triggered.
Name
opt?
Type
{ notify: boolean }
Description
An optional object to control the behavior of the event handler. If true, and the event was previously dispatched, handler will be called immediately with the latest payload

`off()`

Removes an event handler for a specific Clerk event.

type OffEventListener = <E extends ClerkEvent>(event: E, handler: EventHandler<E>) => void

Parameters

Name
event
Type
E
Description
The event to remove the handler from. Currently, the only supported event is status.
Name
handler
Type
EventHandler<E>
Description
The handler to remove.

`redirectToCreateOrganization()`

Redirects to the configured URL where <CreateOrganization /> is mounted. This method uses the navigate() method under the hood.

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function redirectToCreateOrganization(): Promise<unknown>

`redirectToOrganizationProfile()`

Redirects to the configured URL where <OrganizationProfile /> is mounted. This method uses the navigate() method under the hood.

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function redirectToOrganizationProfile(): Promise<unknown>

Redirects to the sign-in URL, as configured in your application's instance settings. This method uses the navigate() method under the hood.

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function redirectToSignIn(options?: SignInRedirectOptions): Promise<unknown>

Parameters

Name
options?
Type
SignInRedirectOptions | undefined
Description
Options to use in the redirect, such as signInForceRedirectUrl and signInFallbackRedirectUrl.

Redirects to the sign-up URL, as configured in your application's instance settings. This method uses the navigate() method under the hood.

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function redirectToSignUp(options?: SignUpRedirectOptions): Promise<unknown>

Parameters

Name
options?
Type
SignUpRedirectOptions | undefined
Description
Options to use in the redirect, such as signUpForceRedirectUrl and signUpFallbackRedirectUrl.

`redirectToUserProfile()`

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function redirectToUserProfile(): Promise<unknown>

`redirectWithAuth()`

Redirects to the provided URL after appending authentication credentials. For development instances, this method decorates the URL with an auth token to maintain authentication state. For production instances, the standard session cookie is used.

Returns a promise that can be awaited in order to listen for the navigation to finish. The inner value should not be relied on, as it can change based on the framework it's used within.

function redirectWithAuth(to: string): Promise<unknown>

Parameters

Name
to
Type
string | undefined
Description
The route to navigate to.

Redirects to the configured after-sign-in URL.

function redirectToAfterSignIn(): void

Redirects to the configured after-sign-up URL.

function redirectToAfterSignUp(): void

`redirectToAfterSignOut()`

Redirects to the configured after-sign-out URL.

function redirectToAfterSignOut(): void

`redirectToWaitlist()`

Redirects to the configured URL where <Waitlist /> is mounted.

function redirectToWaitlist(): void

`redirectToTasks()`

Redirects to the configured URL where session tasks are mounted.

function redirectToTasks(options?: TasksRedirectOptions): Promise<unknown>

Parameters

Name
options?
Type
TasksRedirectOptions | undefined
Description
Options to control the redirect (e.g. redirect URL after tasks are complete).

`setActive()`

A method used to set the current session and/or Organization for the client. Accepts a SetActiveParams object.

function setActive(params: SetActiveParams): Promise<void>

Using the `navigate()` parameter

Clerk relies on the __client cookie to authenticate requests to Clerk's Frontend API (the clerk. subdomain). Safari's Intelligent Tracking Prevention (ITP) limits cookies set via API responses from CNAME-cloaked subdomains to 7 days, and this cookie is subject to that limitation. This means sessions can unexpectedly expire for Safari users who don't visit your app frequently.

When using a custom navigate() callback with setActive(), use the decorateUrl() function to wrap your destination URLs. This enables automatic cookie refresh when needed:

await clerk.setActive({
  session: newSession,
  navigate: ({ session, decorateUrl }) => {
    const url = decorateUrl('/dashboard')

    // decorateUrl may return an absolute URL for cookie refresh
    if (url.startsWith('http')) {
      window.location.href = url
    } else {
      window.location.href = url
    }
  },
})

The decorateUrl function:

Returns a URL that redirects through Clerk's API to refresh the session cookie when needed.
Returns the original URL unchanged when cookie refresh is not needed.
Is safe to always use - it only modifies the URL when necessary.

Note

If you're using a client-side router (Next.js, React Router, etc.), the if/else pattern above ensures full-page navigation only happens when cookie refresh is needed, preserving client-side navigation otherwise.

`signOut()`

In a multi-session application: Signs out the active user from all sessions
In a single-session context: Signs out the active user from the current session

The current client will be deleted. You can specify a specific session to sign out by passing the sessionId parameter.

function signOut(options?: SignOutOptions): Promise<void>
// OR
function signOut(
  signOutCallback?: () => void | Promise<any>,
  options?: SignOutOptions,
): Promise<void>

`SignOutOptions`

Name
sessionId?
Type
string
Description
Specify a specific session to sign out. Useful for multi-session applications.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after sign out is complete.

mountOrganizationSwitcher()
unmountOrganizationSwitcher()
__experimental_prefetchOrganizationSwitcher() — Prefetches organization switcher data when using standalone mode to avoid loading states. Experimental.

Clerk class

Feedback

`Clerk` class