Clerk class - Objects - Next.js | Clerk Docs
Clerk class
- Example
- Properties
- Methods
addListener()authenticateWithBase()authenticateWithCoinbaseWallet()authenticateWithGoogleOneTap()authenticateWithMetamask()authenticateWithOKXWallet()authenticateWithSolana()authenticateWithWeb3()buildAfterMultiSessionSingleSignOutUrl()buildAfterSignInUrl()buildAfterSignOutUrl()buildAfterSignUpUrl()buildCreateOrganizationUrl()buildNewSubscriptionRedirectUrl()buildOrganizationProfileUrl()buildSignInUrl()buildSignUpUrl()buildTasksUrl()buildUrlWithAuth()buildUserProfileUrl()buildWaitlistUrl()createOrganization()getOrganization()handleEmailLinkVerification()handleGoogleOneTapCallback()handleRedirectCallback()handleUnauthenticated()joinWaitlist()load()navigate()off()on()openSignIn()redirectToAfterSignIn()redirectToAfterSignOut()redirectToCreateOrganization()redirectToOrganizationProfile()redirectToSignIn()redirectToSignUp()redirectToTasks()redirectToUserProfile()redirectToWaitlist()redirectWithAuth()setActive()setProtectAssertion()signOut()
Available in other SDKs
Copy as markdownMarkdownCopy as markdown
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/page.tsx
'use client'
import { useClerk } from '@clerk/nextjs'
export default function Page() {
const clerk = useClerk()
return <button onClick={() => clerk.openSignIn({})}>Sign in</button>
}
Properties
- Name
apiKeysTypeAPIKeysNamespaceDescription
The APIKeys object used for managing API keys.
- Name
billingTypeBillingNamespaceDescription
The Billing object used for managing billing.
- Name
clientTypeundefined | ClientResourceDescription
The Client object for the current window.
- Name
domainTypestringDescription
The current Clerk app's domain. Prefixed with clerk. on production if not already prefixed. Returns "" when ran on the server.
- Name
instanceTypeTypeundefined | "production" | "development"Description
Indicates whether the Clerk instance is running in a production or development environment.
- Name
isSatelliteTypebooleanDescription
Indicates whether the instance is a satellite app.
- Name
isSignedInTypebooleanDescription
Indicates whether the current user has a valid signed-in client session.
- Name
isStandardBrowserTypeundefined | booleanDescription
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
loadedTypebooleanDescription
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
oauthApplicationTypeOAuthApplicationNamespaceDescription
OAuth application helpers (e.g., consent metadata for custom consent UIs).
- Name
organizationTypeundefined | null | OrganizationResourceDescription
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
proxyUrlTypeundefined | stringDescription
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
publishableKeyTypestringDescription
Your Clerk Publishable Key.
- Name
sdkMetadataTypeundefined | { 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
sdkMetadata.environment?TypestringDescription
Typically this will be the NODE_ENV that the SDK is currently running in.
- Name
sdkMetadata.nameTypestringDescription
The npm package name of the SDK.
- Name
sdkMetadata.versionTypestringDescription
The npm package version of the SDK.
- Name
sessionTypeundefined | null | SignedInSessionResourceDescription
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
statusType"error" | "degraded" | "loading" | "ready"Description
The status of the Clerk instance. Possible values are:
"error": Set when hotloadingclerk-jsorClerk.load()failed."loading": Set during initialization."ready": Set when Clerk is fully operational."degraded": Set when Clerk is partially operational.
Name
telemetryTypeundefined | { isDebug: boolean; isEnabled: boolean; record: void; recordLog: void; }Description
Telemetry configuration.
- Name
telemetry.isDebugTypebooleanDescription
If true, telemetry events are only logged to the console and not sent to Clerk.
- Name
telemetry.isEnabledTypebooleanDescription
Indicates whether telemetry is enabled.
- Name
uiVersionTypeundefined | stringDescription
The version of @clerk/ui that is currently loaded, or undefined if the prebuilt UI has not been loaded yet.
- Name
userTypeundefined | null | UserResourceDescription
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
versionTypeundefined | stringDescription
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
callbackType(emission: { client: ClientResource; organization?: null | OrganizationResource; session?: null | SignedInSessionResource; user?: null | UserResource; }) => voidDescription
The function to call when Clerk resources change.
- Name
options?Type{ skipInitialEmit?: boolean; }Description
Optional configuration.
- Name
options?.skipInitialEmit?TypebooleanDescription
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?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
redirectUrl?TypestringDescription
The full URL or path to navigate to after a successful sign-in or sign-up.
- Name
signUpContinueUrl?TypestringDescription
The URL to navigate to if the sign-up process is missing user information.
- Name
unsafeMetadata?TypeSignUpUnsafeMetadataDescription
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?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
redirectUrl?TypestringDescription
The full URL or path to navigate to after a successful sign-in or sign-up.
- Name
signUpContinueUrl?TypestringDescription
The URL to navigate to if the sign-up process is missing user information.
- Name
unsafeMetadata?TypeSignUpUnsafeMetadataDescription
authenticateWithGoogleOneTap()
Authenticates user using a Google token generated from Google identity services.
function authenticateWithGoogleOneTap(params: AuthenticateWithGoogleOneTapParams): Promise<SignInResource | SignUpResource>
AuthenticateWithGoogleOneTapParams
- Name
legalAccepted?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
tokenTypestringDescription
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?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
redirectUrl?TypestringDescription
The full URL or path to navigate to after a successful sign-in or sign-up.
- Name
signUpContinueUrl?TypestringDescription
The URL to navigate to if the sign-up process is missing user information.
- Name
unsafeMetadata?TypeSignUpUnsafeMetadataDescription
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?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
redirectUrl?TypestringDescription
The full URL or path to navigate to after a successful sign-in or sign-up.
- Name
signUpContinueUrl?TypestringDescription
The URL to navigate to if the sign-up process is missing user information.
- Name
unsafeMetadata?TypeSignUpUnsafeMetadataDescription
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?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
redirectUrl?TypestringDescription
The full URL or path to navigate to after a successful sign-in or sign-up.
- Name
signUpContinueUrl?TypestringDescription
The URL to navigate to if the sign-up process is missing user information.
Name
unsafeMetadata?TypeSignUpUnsafeMetadataDescriptionName
walletNameTypestringDescription
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?TypebooleanDescription
A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
protectCheckUrl?TypestringDescription
The URL to navigate to if a Clerk Protect challenge gates the sign-in flow.
- Name
redirectUrl?TypestringDescription
The full URL or path to navigate to after a successful sign-in or sign-up.
- Name
secondFactorUrl?TypestringDescription
The URL to navigate to if second factor is required.
- Name
signUpContinueUrl?TypestringDescription
The URL to navigate to if the sign-up process is missing user information.
- Name
signUpProtectCheckUrl?TypestringDescription
The URL to navigate to if a Clerk Protect challenge gates the sign-up flow (when the web3 attempt falls back to sign-up).
- Name
strategyType"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?TypeSignUpUnsafeMetadataDescriptionName
walletName?TypestringDescription
The name of the wallet to use for authentication.
buildAfterMultiSessionSingleSignOutUrl()
Returns the configured afterMultiSessionSingleSignOutUrl of the instance.
function buildAfterMultiSessionSingleSignOutUrl(): string
buildAfterSignInUrl()
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
buildAfterSignUpUrl()
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
function buildCreateOrganizationUrl(): string
buildNewSubscriptionRedirectUrl()
Returns the configured newSubscriptionRedirectUrl of the instance.
function buildNewSubscriptionRedirectUrl(): string
buildOrganizationProfileUrl()
Returns the configured URL where
function buildOrganizationProfileUrl(): string
buildSignInUrl()
Returns the configured URL where
function buildSignInUrl(opts?: RedirectOptions): string
RedirectOptions
- Name
redirectUrl?Typestring | nullDescription
Full URL or path to navigate to after a successful action.
- Name
signInFallbackRedirectUrl?Typestring | nullDescription
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?Typestring | nullDescription
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?Typestring | nullDescription
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?Typestring | nullDescription
If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.
buildSignUpUrl()
Returns the configured URL where
function buildSignUpUrl(opts?: RedirectOptions): string
RedirectOptions
- Name
redirectUrl?Typestring | nullDescription
Full URL or path to navigate to after a successful action.
Name
signInFallbackRedirectUrl?Typestring | nullDescriptionName
signInForceRedirectUrl?Typestring | nullDescriptionName
signUpFallbackRedirectUrl?Typestring | nullDescriptionName
signUpForceRedirectUrl?Typestring | nullDescription
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
toTypestringDescription
The route to create a URL towards.
buildUserProfileUrl()
Returns the configured URL where
function buildUserProfileUrl(): string
buildWaitlistUrl()
Returns the configured URL where
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?TypeRecord<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
function createOrganization(params: CreateOrganizationParams): Promise<OrganizationResource>
CreateOrganizationParams
- Name
nameTypestringDescription
The name of the Organization.
- Name
slug?TypestringDescription
The slug of the Organization.
getOrganization()
Gets a single Organization by ID.
function getOrganization(organizationId: string): Promise<OrganizationResource>
Parameters
- Name
organizationIdTypestringDescription
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
paramsType{ 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() => voidDescription
Callback function to be executed after successful email link verification on another device.
- Name
params.redirectUrl?TypestringDescription
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?TypestringDescription
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.
- Redirects accordingly using the provided URLs (both optional):
- 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
signInOrUpTypeSignInResource | SignUpResourceDescription
The resource returned from the initial authenticateWithGoogleOneTap() call (before redirect).
- Name
paramsTypeHandleOAuthCallbackParamsDescription
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
paramsTypeHandleOAuthCallbackParamsDescription
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
emailAddressTypestringDescription
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?Typestring | nullDescription
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?Typestring | nullDescription
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?Typestring[]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?TypeanyDescription
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?TypeAutocomplete<{ 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?Typeboolean | (url: URL) => booleanDescription
Indicates whether the current application should behave as a satellite app. Unlike domain, which must be set in the Clerk constructor, isSatellite must be set in load().
- Name
localization?TypeLocalizationResourceDescription
An object to localize your components. Will only affect Clerk Components and not Account Portal pages.
- Name
newSubscriptionRedirectUrl?Typestring | nullDescription
The full URL or path to navigate to after the user completes the checkout and clicks the "Continue" button.
- Name
polling?TypebooleanDescription
Indicates whether Clerk should poll against Clerk's backend every 5 minutes. Defaults to true.
- Name
protectAssertion?Typestring | () => undefined | string | Promise<undefined | string>Description
A Clerk Protect assertion — a short-lived, signed token you mint from your own backend with the Clerk Backend API — carrying key/value pairs your Protect rules can read. Clerk attaches it to sign-in and sign-up requests. Pass a string if you already have one, or a function to have it re-read for each request. Prefer the function when a page can outlive the token: assertions are short-lived by design, and a string captured here stops applying once it expires. Can also be set later with Clerk.setProtectAssertion().
- Name
routerDebug?TypebooleanDescription
If true, the router will log debug information to the console.
- Name
routerPush()Type(to: string, metadata?: { windowNavigate: (to: URL | string) => void; }) => unknownDescription
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; }) => unknownDescription
A function which takes the destination path as an argument and performs a "replace" navigation.
- Name
satelliteAutoSync?TypebooleanDescription
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?TypestringDescription
Typically this will be the NODE_ENV that the SDK is currently running in.
- Name
sdkMetadata.nameTypestringDescription
The npm package name of the SDK.
- Name
sdkMetadata.versionTypestringDescription
The npm package version of the SDK.
- Name
selectInitialSession()?Type(client: ClientResource) => SignedInSessionResource | nullDescription
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?Typestring | nullDescriptionName
signInForceRedirectUrl?Typestring | nullDescriptionName
signInUrl?TypestringDescription
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?Typestring | nullDescriptionName
signUpForceRedirectUrl?Typestring | nullDescriptionName
signUpUrl?TypestringDescriptionName
standardBrowser?TypebooleanDescription
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?TypestringDescription
The support email address for display in authentication screens. Will only affect Clerk Components and not Account Portal pages.
- Name
taskUrls?TypePartial<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?Typefalse | { 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?TypebooleanDescription
Whether telemetry events are only logged to the console and not sent to Clerk.
- Name
telemetry.disabled?TypebooleanDescription
Whether telemetry will be collected.
- Name
telemetry.perEventSampling?TypebooleanDescription
Whether the sampling rates provided per telemetry event will be ignored and all events will be sent. Defaults to true.
- Name
touchSession?TypebooleanDescription
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?TypeClerkUIConstructor | Promise<ClerkUIConstructor>Description
Pass the ui export from @clerk/ui.
- Name
waitlistUrl?TypestringDescription
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
toTypestringDescription
The URL or relative path to navigate to.
- Name
options?Type{ metadata?: RouterMetadata; replace?: boolean; }Description
Optional configuration.
- Name
options?.metadata?TypeRouterMetadataDescription
Router metadata.
- Name
options?.replace?TypebooleanDescription
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
eventTypeEDescription
The event name to unsubscribe from.
- Name
handlerTypeEventHandler<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
eventTypeEDescription
The event name to subscribe to.
- Name
handlerTypeEventHandler<E>Description
The callback function to execute when the event is dispatched.
- Name
opt?Type{ notify: boolean; }Description
Optional configuration.
- Name
opt?.notify?TypebooleanDescription
If true and the event was previously dispatched, handler will be called immediately with the latest payload.
openSignIn()
Opens the Clerk SignIn component in a modal.
function openSignIn(props?: SignInModalProps): void
Parameters
- Name
props?TypeSignInModalPropsDescription
Optional sign in configuration parameters.
redirectToAfterSignIn()
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
function redirectToCreateOrganization(): Promise<unknown>
redirectToOrganizationProfile()
Redirects to the configured URL where
function redirectToOrganizationProfile(): Promise<unknown>
redirectToSignIn()
Redirects to the sign-in URL, as configured in your application's instance settings. This method uses the navigate() method under the hood.
function redirectToSignIn(opts?: SignInRedirectOptions): Promise<unknown>
Parameters
- Name
opts?TypeSignInRedirectOptionsDescription
Options to control the redirect.
redirectToSignUp()
Redirects to the sign-up URL, as configured in your application's instance settings. This method uses the navigate() method under the hood.
function redirectToSignUp(opts?: SignUpRedirectOptions): Promise<unknown>
Parameters
- Name
opts?TypeSignUpRedirectOptionsDescription
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?TypeTasksRedirectOptionsDescription
Options to control the redirect (e.g., redirect URL after tasks are complete).
redirectToUserProfile()
Redirects to the configured URL where
function redirectToUserProfile(): Promise<unknown>
redirectToWaitlist()
Redirects to the configured URL where
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.
function redirectWithAuth(to: string): Promise<unknown>
Parameters
- Name
toTypestringDescription
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?TypeSetActiveNavigateDescription
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?Typenull | string | OrganizationResourceDescription
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?TypestringDescription
The full URL or path to redirect to just before the session and/or organization is set.
- Name
session?Typenull | string | SignedInSessionResourceDescription
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.
setProtectAssertion()
Sets the Protect assertion attached to subsequent sign-in and sign-up requests, replacing
any value supplied via the protectAssertion option. Pass undefined to clear it.
Use this when the token is not available at Clerk.load() time — for example when your
app fetches one from your backend after the page has started. Passing a function instead
of a string has it re-read for each request, which is what you want if the token is
refreshed while the page is open.
function setProtectAssertion(assertion?: string | (() => undefined | string | Promise<undefined | string>)): void
Parameters
- Name
assertion?Typestring | () => undefined | string | Promise<undefined | string>Description
A token minted by your backend, a function returning one, or undefined.
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?TypestringDescription
Specify a redirect URL to navigate to after sign-out is complete.
- Name
sessionId?TypestringDescription
Specify a specific session to sign out. Useful for multi-session applications.
Feedback
What did you think of this content?
It was helpfulIt was not helpfulI have feedback
Last updated onSep 3, 2026
Support