`Clerk` class

Example
Properties
Methods

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.

app/routes/home.tsx

import { useClerk } from '@clerk/react-router'

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

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

Properties

Name
apiKeys
Type
APIKeysNamespace
Description
The APIKeys object used for managing API keys.
Name
billing
Type
BillingNamespace
Description
The Billing object used for managing billing.
Name
client
Type
undefined | ClientResource
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
undefined | "production" | "development"
Description
Indicates whether the Clerk instance is running in a production or development environment.
Name
isSatellite
Type
boolean
Description
Indicates whether the instance is a satellite app.
Name
isSignedIn
Type
boolean
Description
Indicates whether the current user has a valid signed-in client session.
Name
isStandardBrowser
Type
undefined | boolean
Description
Indicates whether 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
loaded
Type
boolean
Description
Indicates whether the Clerk object is ready for use. Set to false when the status is "loading". Set to true when the status is "ready" or "degraded".
Name
oauthApplication
Type
OAuthApplicationNamespace
Description
OAuth application helpers (e.g. consent metadata for custom consent UIs).
Name
organization
Type
undefined | null | OrganizationResource
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
undefined | string
Description
Required for applications that run behind a reverse proxy. Your Clerk app's proxy URL. Can be either a relative path (/__clerk) or a full URL (https://<your-domain>/__clerk).
Name
publishableKey
Type
string
Description
Your Clerk Publishable Key.
Name
sdkMetadata
Type
undefined | { environment?: string; name: string; version: string; }
Description
If present, contains information about the SDK that the host application is using. For example, if Clerk is loaded through @clerk/nextjs, this would be { 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
undefined | null | SignedInSessionResource
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
"error" | "degraded" | "loading" | "ready"
Description
The status of the Clerk instance. Possible values are:

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

"loading": Set during initialization.

"ready": Set when Clerk is fully operational.

"degraded": Set when Clerk is partially operational.
Name
telemetry
Type
undefined | { isDebug: boolean; isEnabled: boolean; record: void; recordLog: void; }
Description
Telemetry configuration.
Name
user
Type
undefined | null | UserResource
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
undefined | string
Description
The Clerk SDK version number.

Methods

`addListener()`

Register a listener that triggers a callback whenever a change in the Client, Session, User, or Organization resources occurs. This method is primarily used to build frontend SDKs like @clerk/react.

Allows hooking up at different steps in the sign up, sign in processes.

Some important checkpoints:

When there is an active session, user === session.user.
When there is no active session, user and session will both be null.
When a session is loading, user and session will be undefined.

Returns an UnsubscribeCallback function that can be used to remove the listener from the Clerk object.

function addListener(callback: (emission: { client: ClientResource; organization?: null | OrganizationResource; session?: null | SignedInSessionResource; user?: null | UserResource }) => void, options?: { skipInitialEmit?: boolean }): UnsubscribeCallback

Parameters

Name
callback
Type
(emission: { client: ClientResource; organization?: null | OrganizationResource; session?: null | SignedInSessionResource; user?: null | UserResource; }) => void
Description
The function to call when Clerk resources change.
Name
options?
Type
{ skipInitialEmit?: boolean; }
Description
Optional configuration.
Name
options?.skipInitialEmit?
Type
boolean
Description
If true, the callback will not be called immediately after registration. Defaults to false.

`authenticateWithBase()`

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

function authenticateWithBase(params?: AuthenticateWithBaseParams): Promise<unknown>

`AuthenticateWithBaseParams`

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.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string
Description
The URL to navigate to if the sign-up process is missing user information.
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.

`authenticateWithCoinbaseWallet()`

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

function authenticateWithCoinbaseWallet(params?: AuthenticateWithCoinbaseWalletParams): Promise<unknown>

`AuthenticateWithCoinbaseWalletParams`

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.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string
Description
The URL to navigate to if the sign-up process is missing user information.
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.

`authenticateWithGoogleOneTap()`

Authenticates user using a Google token generated from Google identity services.

function authenticateWithGoogleOneTap(params: AuthenticateWithGoogleOneTapParams): Promise<SignInResource | SignUpResource>

`AuthenticateWithGoogleOneTapParams`

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

`authenticateWithMetamask()`

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

function authenticateWithMetamask(params?: AuthenticateWithMetamaskParams): Promise<unknown>

`AuthenticateWithMetamaskParams`

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.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string
Description
The URL to navigate to if the sign-up process is missing user information.
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.

`authenticateWithOKXWallet()`

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

function authenticateWithOKXWallet(params?: AuthenticateWithOKXWalletParams): Promise<unknown>

`AuthenticateWithOKXWalletParams`

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.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string
Description
The URL to navigate to if the sign-up process is missing user information.
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.

`authenticateWithSolana()`

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

function authenticateWithSolana(params: AuthenticateWithSolanaParams): Promise<unknown>

`AuthenticateWithSolanaParams`

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.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
signUpContinueUrl?
Type
string
Description
The URL to navigate to if the sign-up process is missing user information.
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
walletName
Type
string
Description
The name of the Solana wallet to use for authentication.

`authenticateWithWeb3()`

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

function authenticateWithWeb3(params: ClerkAuthenticateWithWeb3Params): Promise<unknown>

`ClerkAuthenticateWithWeb3Params`

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.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
redirectUrl?
Type
string
Description
The full URL or path to navigate to after a successful sign-in or sign-up.
Name
secondFactorUrl?
Type
string
Description
The URL to navigate to if second factor is required.
Name
signUpContinueUrl?
Type
string
Description
The URL to navigate to if the sign-up process is missing user information.
Name
strategy
Type
"web3_metamask_signature" | "web3_base_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_signature" | "web3_solana_signature"
Description
The strategy to use for the sign-in flow.
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
walletName?
Type
string
Description
The name of the wallet to use for authentication.

`buildAfterMultiSessionSingleSignOutUrl()`

Returns the configured afterMultiSessionSingleSignOutUrl of the instance.

function buildAfterMultiSessionSingleSignOutUrl(): string

Returns the configured afterSignInUrl of the instance.

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

Parameters

Name
params?
Type
{ params?: URLSearchParams; }
Description
Optional query parameters to append to the URL.

`buildAfterSignOutUrl()`

Returns the configured afterSignOutUrl of the instance.

function buildAfterSignOutUrl(): string

Returns the configured afterSignUpUrl of the instance.

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

Parameters

Name
params?
Type
{ params?: URLSearchParams; }
Description
Optional query parameters to append to the URL.

`buildCreateOrganizationUrl()`

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

function buildCreateOrganizationUrl(): string

`buildNewSubscriptionRedirectUrl()`

Returns the configured newSubscriptionRedirectUrl of the instance.

function buildNewSubscriptionRedirectUrl(): 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(opts?: RedirectOptions): string

`RedirectOptions`

Name
redirectUrl?
Type
string | null
Description
Full URL or path to navigate to after a successful action.
Name
signInFallbackRedirectUrl?
Type
string | null
Description
The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.
Name
signInForceRedirectUrl?
Type
string | null
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
signUpFallbackRedirectUrl?
Type
string | null
Description
The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.
Name
signUpForceRedirectUrl?
Type
string | null
Description
If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.

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

function buildSignUpUrl(opts?: RedirectOptions): string

`RedirectOptions`

Name
redirectUrl?
Type
string | null
Description
Full URL or path to navigate to after a successful action.
Name
signInFallbackRedirectUrl?
Type
string | null
Description
The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.
Name
signInForceRedirectUrl?
Type
string | null
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
signUpFallbackRedirectUrl?
Type
string | null
Description
The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.
Name
signUpForceRedirectUrl?
Type
string | null
Description
If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.

`buildTasksUrl()`

Returns the configured URL where session tasks are mounted.

function buildTasksUrl(): string

`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 configured URL where <UserProfile /> is mounted or a custom user-profile page is rendered.

function buildUserProfileUrl(): string

`buildWaitlistUrl()`

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

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

Parameters

Name
opts?
Type
{ initialValues?: Record<string, string>; }
Description
Options to control the waitlist URL.
Name
opts?.initialValues?
Type
Record<string, string>
Description
Initial values to prefill the waitlist form.

`createOrganization()`

Creates an Organization programmatically, adding the current user as admin. Returns an Organization object.

Note

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

function createOrganization(params: CreateOrganizationParams): Promise<OrganizationResource>

`CreateOrganizationParams`

Name
name
Type
string
Description
The name of the Organization.
Name
slug?
Type
string
Description
The slug of the Organization.

`getOrganization()`

Gets a single Organization by ID.

function getOrganization(organizationId: string): Promise<OrganizationResource>

Parameters

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

`handleEmailLinkVerification()`

Completes an email link verification flow started by Clerk.client.signIn.createEmailLinkFlow or Clerk.client.signUp.createEmailLinkFlow, 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: { onVerifiedOnOtherDevice?: () => void; redirectUrl?: string; redirectUrlComplete?: string }, customNavigate?: (to: string) => Promise<unknown>): Promise<unknown>

Parameters

Name
params
Type
{ onVerifiedOnOtherDevice?: () => void; redirectUrl?: string; redirectUrlComplete?: string; }
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
params.onVerifiedOnOtherDevice?
Type
() => void
Description
Callback function to be executed after successful email link verification on another device.
Name
params.redirectUrl?
Type
string
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
params.redirectUrlComplete?
Type
string
Description
The full URL to navigate to after successful email link verification on completed sign-up or sign-in on the same device.
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.

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 for more usage details.

`handleGoogleOneTapCallback()`

Completes a Google One Tap redirection flow started by authenticateWithGoogleOneTap(). This method should be called after the user is redirected back from visiting the Google One Tap prompt.

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

Parameters

Name
signInOrUp
Type
SignInResource | SignUpResource
Description
The resource returned from the initial authenticateWithGoogleOneTap() call (before redirect).
Name
params
Type
HandleOAuthCallbackParams
Description
Additional props that define where the user will be redirected to at the end of a successful Google One Tap 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.

`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, customNavigate?: (to: string) => Promise<unknown>): Promise<unknown>

Parameters

Name
params
Type
HandleOAuthCallbackParams
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.

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

`handleUnauthenticated()`

Handles a 401 response from the Frontend API by refreshing the Client and Session object accordingly.

function handleUnauthenticated(): 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(params: JoinWaitlistParams): Promise<WaitlistResource>

`JoinWaitlistParams`

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

`load()`

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

function load(opts?: Without<ClerkOptions, 'isSatellite'>): Promise<void>

`ClerkOptions`

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

Name
afterMultiSessionSingleSignOutUrl?
Type
string | null
Description
The full URL or path to navigate to after signing out the current user is complete. This option applies to multi-session applications.
Name
afterSignOutUrl?
Type
string | null
Description
The full URL or path to navigate to after successful sign out.
Name
allowedRedirectOrigins?
Type
(string | RegExp)[]
Description
An 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
string[]
Description
An 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
appearance?
Type
any
Description
An object to style your components. Will only affect Clerk Components and not Account Portal pages. See the Appearance docs for more information.
Name
experimental?
Type
Autocomplete<{ commerce: boolean; persistClient: boolean; rethrowOfflineNetworkErrors: boolean; runtimeEnvironment: "headless"; }, Record<string, any>>
Description
Enable experimental flags to gain access to new features. These flags are not guaranteed to be stable and may change drastically in between patch or minor versions.
Name
isSatellite?
Type
boolean | (url: URL) => boolean
Description
Indicates whether the application is a satellite application.
Name
localization?
Type
LocalizationResource
Description
An object to localize your components. Will only affect Clerk Components and not Account Portal pages.
Name
newSubscriptionRedirectUrl?
Type
string | null
Description
The full URL or path to navigate to after the user completes the checkout and clicks the "Continue" button.
Name
polling?
Type
boolean
Description
Indicates whether Clerk should poll against Clerk's backend every 5 minutes. Defaults to true.
Name
routerDebug?
Type
boolean
Description
If true, the router will log debug information to the console.
Name
routerPush()
Type
(to: string, metadata?: { windowNavigate: (to: URL | string) => void; }) => unknown
Description
A function which takes the destination path as an argument and performs a "push" navigation.
Name
routerReplace()
Type
(to: string, metadata?: { windowNavigate: (to: URL | string) => void; }) => unknown
Description
A function which takes the destination path as an argument and performs a "replace" navigation.
Name
satelliteAutoSync?
Type
boolean
Description
Controls whether satellite apps automatically sync with the primary domain on initial page load. When false (default), satellite apps will skip the automatic handshake if no session cookies exist, and only trigger the handshake after an explicit sign-in action. This provides the best performance by showing the satellite app immediately without attempting to sync state first. When true, satellite apps will automatically trigger a handshake redirect to sync authentication state with the primary domain on first load, even if no session cookies exist. Use this if you want users who are already signed in on the primary domain to be automatically recognized on the satellite. Defaults to false.
Name
sdkMetadata?
Type
{ environment?: string; name: string; version: string; }
Description
Contains information about the SDK that the host application is using. You don't need to set this value yourself unless you're developing an SDK.
Name
sdkMetadata.environment?
Type
string
Description
Typically this will be the NODE_ENV that the SDK is currently running in.
Name
sdkMetadata.name
Type
string
Description
The npm package name of the SDK.
Name
sdkMetadata.version
Type
string
Description
The npm package version of the SDK.
Name
selectInitialSession()?
Type
(client: ClientResource) => SignedInSessionResource | null
Description
By default, the last signed-in session is used during client initialization. This option allows you to override that behavior, e.g. by selecting a specific session.
Name
signInFallbackRedirectUrl?
Type
string | null
Description
The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.
Name
signInForceRedirectUrl?
Type
string | null
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
signInUrl?
Type
string
Description
This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. It is required to be set for a satellite application in a development instance. It's recommended to use the environment variable instead.
Name
signUpFallbackRedirectUrl?
Type
string | null
Description
The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.
Name
signUpForceRedirectUrl?
Type
string | null
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
signUpUrl?
Type
string
Description
This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. It is required to be set for a satellite application in a development instance. It's recommended to use the environment variable instead.
Name
standardBrowser?
Type
boolean
Description
Indicates whether ClerkJS is loaded with the assumption that cookies can be set (browser setup). On native platforms this value must be set to false.
Name
supportEmail?
Type
string
Description
The support email address for display in authentication screens. Will only affect Clerk Components and not Account Portal pages.
Name
taskUrls?
Type
Partial<Record<SessionTask["key"], string>>
Description
Customize the URL paths users are redirected to after sign-in or sign-up when specific session tasks need to be completed. When undefined, it uses Clerk's default task flow URLs. Defaults to undefined.
Name
telemetry?
Type
false | { debug?: boolean; disabled?: boolean; perEventSampling?: boolean; }
Description
Controls whether or not Clerk will collect telemetry data. If set to debug, telemetry events are only logged to the console and not sent to Clerk.
Name
telemetry.debug?
Type
boolean
Description
If true, telemetry events are only logged to the console and not sent to Clerk
Name
telemetry.disabled?
Type
boolean
Description
If true, telemetry will not be collected.
Name
telemetry.perEventSampling?
Type
boolean
Description
If false, the sampling rates provided per telemetry event will be ignored and all events will be sent. Defaults to true.
Name
touchSession?
Type
boolean
Description
By default, the Clerk Frontend API touch endpoint is called during page focus to keep the last active session alive. This option allows you to disable this behavior.
Name
ui?
Type
{ ClerkUI?: ClerkUIConstructor | Promise<ClerkUIConstructor>; }
Description
Only required if you're bundling Clerk's UI (@clerk/ui) instead of loading it from the Clerk CDN. Provide the UI module to embed Clerk's prebuilt authentication components directly in your application.
Name
ui.ClerkUI?
Type
ClerkUIConstructor | Promise<ClerkUIConstructor>
Description
Pass the ui export from @clerk/ui.
Name
waitlistUrl?
Type
string
Description
The full URL or path to the waitlist page. If undefined, will redirect to the Account Portal waitlist page.

`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, options?: { metadata?: RouterMetadata; replace?: boolean }): Promise<unknown> | void

Parameters

Name
to
Type
string
Description
The URL or relative path to navigate to.
Name
options?
Type
{ metadata?: RouterMetadata; replace?: boolean; }
Description
Optional configuration.
Name
options?.metadata?
Type
RouterMetadata
Description
Router metadata.
Name
options?.replace?
Type
boolean
Description
If true, replace the current history entry instead of pushing a new one.

`off()`

Removes an event handler for a specific Clerk event.

function off<E>(event: E, handler: EventHandler<E>): void

Parameters

Name
event
Type
E
Description
The event name to unsubscribe from.
Name
handler
Type
EventHandler<E>
Description
The callback function to remove.

`on()`

Registers an event handler for a specific Clerk event.

function on<E>(event: E, handler: EventHandler<E>, opt?: { notify: boolean }): void

Parameters

Name
event
Type
E
Description
The event name to subscribe to.
Name
handler
Type
EventHandler<E>
Description
The callback function to execute when the event is dispatched.
Name
opt?
Type
{ notify: boolean; }
Description
Optional configuration.
Name
opt?.notify?
Type
boolean
Description
If true and the event was previously dispatched, handler will be called immediately with the latest payload.

Redirects to the configured afterSignIn URL.

function redirectToAfterSignIn(): void

`redirectToAfterSignOut()`

Redirects to the configured afterSignOut URL.

function redirectToAfterSignOut(): void

`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(opts?: SignInRedirectOptions): Promise<unknown>

Parameters

Name
opts?
Type
SignInRedirectOptions
Description
Options to control the redirect.

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(opts?: SignUpRedirectOptions): Promise<unknown>

Parameters

Name
opts?
Type
SignUpRedirectOptions
Description
Options to control the redirect.

`redirectToTasks()`

Redirects to the configured URL where session tasks are mounted.

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

Parameters

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

`redirectToUserProfile()`

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

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>

`redirectToWaitlist()`

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

function redirectToWaitlist(): void

`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
Description
The URL to redirect to.

`setActive()`

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

If the session param is null, the active session is deleted. In a similar fashion, if the organization param is null, the current organization is removed as active.

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

`SetActiveParams`

Name
navigate?
Type
SetActiveNavigate
Description
A custom navigation function to be called just before the session and/or Organization is set. When provided, it takes precedence over the redirectUrl parameter for navigation. The callback receives a decorateUrl function that should be used to wrap destination URLs. This enables Safari ITP cookie refresh when needed. The decorated URL may be an external URL (starting with https://) that requires window.location.href instead of client-side navigation. See the section on using the navigate() parameter for more details.
Name
organization?
Type
null | string | OrganizationResource
Description
The Organization resource or Organization ID/slug (string version) to be set as active in the current session. If null, the currently Active Organization is removed as active.
Name
redirectUrl?
Type
string
Description
The full URL or path to redirect to just before the session and/or organization is set.
Name
session?
Type
null | string | SignedInSessionResource
Description
The session resource or session ID (string version) to be set as active. If null, the current session is deleted.

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()`

Signs out the current user on single-session instances, or all users on multi-session instances.

function signOut(options?: SignOutOptions): Promise<void>

`SignOutOptions`

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

Last updated on Jun 4, 2026

Edit on GitHub

Clerk class

Feedback

`Clerk` class