Clerk
class
The Clerk
class is the main entrypoint class for the @clerk/clerk-js
package. It contains a number of methods and properties for interacting with the Clerk API.
Properties
- Name
version
- Type
string
- Description
A getter for the Clerk SDK version
- Name
loaded
- Type
boolean
- Description
A getter to see if the
Clerk
object is ready for use or not
- Name
isSatellite
- Type
boolean
- Description
Clerk Flag for satellite apps
- Name
domain
- Type
string
- Description
A getter for the current Clerk app's domain. Prefixed with
clerk.
on production if not already prefixed. Returns""
when ran on the server
- Name
proxyUrl
- Type
string
- Description
A getter for 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
instanceType
- Type
'production' | 'development'
- Description
A getter to see if a Clerk instance is running in production or development mode
- Name
client
- Type
Client
- Description
The
Client
object for the current window.
- Name
session
- Type
Session | null | undefined
- Description
The currently active
Session
, which is guaranteed to be one of the sessions inClient.sessions
. If there is no active session, this field will benull
. If the session is loading, this field will beundefined
.
- Name
user
- Type
User | null | undefined
- Description
A shortcut to
Session.user
which holds the currently activeUser
object. If the session isnull
orundefined
, the user field will match.
- Name
organization
- Type
Organization | null | undefined
- Description
A shortcut to the last active
Session.user.organizationMemberships
which holds an instance of aOrganization
object. If the session isnull
orundefined
, the user field will match.
- Name
publishableKey
- Type
string | undefined
- Description
The Clerk Publishable Key for your instance. This can be found on the API keys page in the Clerk Dashboard.
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/clerk-react
. Returns an UnsubscribeCallback
function that can be used to remove the listener from the Clerk
object.
function addListener(listener: (emission: Resources) => void): UnsubscribeCallback
- 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
- Name
lastOrganizationInvitation
- Type
OrganizationInvitation | null | undefined
- Description
- Name
lastOrganizationMember
- Type
OrganizationMembership | null | undefined
- Description
function authenticateWithMetamask({
redirectUrl,
signUpContinueUrl,
customNavigate,
}?: AuthenticateWithMetamaskParams): Promise<void>
- 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.
function authenticateWithCoinbaseWallet({
redirectUrl,
signUpContinueUrl,
customNavigate,
}?: AuthenticateWithCoinbaseWalletParams): Promise<void>
- 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>
- 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.
function authenticateWithWeb3({
redirectUrl,
signUpContinueUrl,
customNavigate,
strategy,
}: ClerkAuthenticateWithWeb3Params): Promise<void>
- 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.
buildCreateOrganizationUrl()
Returns the configured URL where <CreateOrganization />
is mounted or a custom create-organization page is rendered.
function buildCreateOrganizationUrl(): string
await clerk.buildCreateOrganizationUrl()
buildHomeUrl()
Returns the URL you've configured in the Clerk Dashboard.
function buildHomeUrl(): string
await clerk.buildHomeUrl()
buildOrganizationProfileUrl()
Returns the configured URL where <OrganizationProfile />
is mounted or a custom organization-profile page is rendered.
function buildOrganizationProfileUrl(): string
await clerk.buildOrganizationProfileUrl()
buildSignInUrl()
Returns the configured URL where <SignIn />
is mounted or a custom sign-in page is rendered.
function buildSignInUrl(options?: RedirectOptions): string
- Name
options
- Type
RedirectOptions | undefined
- Description
Options used to control the redirect in the constructed URL.
await clerk.buildSignInUrl({
signInForceRedirectUrl: '/dashboard',
signUpForceRedirectUrl: '/dashboard',
})
buildSignUpUrl()
Returns the configured URL where <SignUp />
is mounted or a custom sign-up page is rendered.
function buildSignUpUrl(options?: RedirectOptions): string
- Name
options
- Type
RedirectOptions | undefined
- Description
Options used to control the redirect in the constructed URL.
await clerk.buildSignUpUrl({
signInForceRedirectUrl: '/dashboard',
signUpForceRedirectUrl: '/dashboard',
})
buildUrlWithAuth()
Decorates the provided URL with the auth token for development instances.
function buildUrlWithAuth(to: string, options?: BuildUrlWithAuthParams): string
- Name
to
- Type
string
- Description
The route to create a URL towards.
- Name
options
- Type
BuildUrlWithAuthParams
- Description
Options to apply toward the URL builder.
await clerk.buildUrlWithAuth('/dashboard')
- Name
useQueryParam
- Type
boolean | null | undefined
- Description
Controls if dev browser JWT is added as a query param.
buildUserProfileUrl()
Returns the URL where <UserProfile />
is mounted or a custom user-profile page is rendered.
function buildUserProfileUrl(): string
await clerk.buildUserProfileUrl()
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)
}
- Name
key
- Type
string
- Description
The Clerk Publishable Key for your instance. This can be found on the API keys page in the Clerk Dashboard.
- 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 fromwindow.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 fromwindow.location.href
.
createOrganization()
Creates an organization programatically. Returns an Organization
object.
function createOrganization({ name, slug }: CreateOrganizationParams): Promise<Organization>
- 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.
await clerk.createOrganization({ name: 'test' })
getOrganization()
Retrieves information for a specific organization.
function getOrganization(organizationId: string): Promise<Organization | undefined>
- Name
organizationId
- Type
string
- Description
The ID of the organization to be found.
Example
The following example demonstrates how to retrieve information about the currently active organization.
await clerk.getOrganization(clerk.organization.id)
handleEmailLinkVerification()
Completes an email link verification flow once we've reached the email link results URL.
function handleEmailLinkVerification(
params: handleEmailLinkVerificationParams,
customNavigate?: ((to: string) => Promise<unknown>) | undefined,
): Promise<unknown>
When users click on email links they get redirected to the URL that was provided during email link verification flow initialization. The URL will contain a couple of important query parameters added by Clerk. These are called __clerk_status
and __clerk_created_session
.
The __clerk_status
query parameter is the outcome of the verification and accepts the following values: verified
, failed
, expired
, or client_mismatch
. client_mismatch
can only be a verification outcome if the Require the same device or browser setting is turned on for sign-ins and sign-ups.
The __clerk_created_session
query parameter will hold the ID of the new session, if one was created as a result of the verification. Since the email link can be opened at any device and not the one that originated the verification, the new session ID might not be available under Client.sessions.
Email link flows can be completed on the same device that they were initiated or on a completely different browser. For example, a user might start the email link flow on their desktop browser, but click on the email link from their mobile phone.
The handleEmailLinkVerification()
method takes care of finalizing the email link flow, depending on the verification outcome.
Upon successful verification, the method will figure out if the sign in or sign up attempt was completed and redirect the user accordingly. As such, it accepts different parameters for the URL it should redirect when sign-in or sign-up is completed and the URL which it should redirect when the sign-in or sign-up attempt is still pending. Both parameters are optional, but you can provide them to the method up front. The final redirect will depend on the sign-in or sign-up attempt's status.
If the email link verification failed or the link expired, this method will throw a EmailLinkError
. Check the error's code
property for details.
Additionally, the handleEmailLinkVerification()
method allows you to execute a callback if the successful verification happened on another device.
In case the email link verification wasn't successful, the handleEmailLinkVerification()
method will throw a EmailLinkError
. You can check the error's code
property to see if the email link expired, or the verification simply failed.
Take a look at the function parameters description 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.
- 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.
Example
See the custom flow guide for a comprehensive example of how to use the handleEmailLinkVerification()
method.
handleRedirectCallback()
Completes a custom OAuth flow started by calling either SignIn.authenticateWithRedirect(params)
or SignUp.authenticateWithRedirect(params)
.
function handleRedirectCallback(
params: HandleOAuthCallbackParams,
customNavigate?: ((to: string) => Promise<unknown>) | undefined,
): Promise<unknown>
- Name
params
- Type
HandleOAuthCallbackParams
- Description
Additional props that define where the user will be redirected to at the end of a successful OAuth 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.
- Name
signInUrl?
- Type
string
- Description
Full URL or path where the SignIn component is mounted.
- Name
signUpUrl?
- Type
string
- Description
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
Full URL or path to navigate during sign in, if identifier verification is required.
- Name
secondFactorUrl
- Type
string | undefined
- Description
Full URL or path to navigate during sign in, if 2FA is enabled.
- Name
resetPasswordUrl
- Type
string
- Description
Full URL or path to navigate during sign in, if the user is required to reset their password.
- Name
continueSignUpUrl
- Type
string | undefined | null
- Description
Full URL or path to navigate after an incomplete sign up.
- Name
verifyEmailAddressUrl
- Type
string | undefined | null
- Description
Full URL or path to navigate after requesting email verification.
- Name
verifyPhoneNumberUrl
- Type
string | undefined | null
- Description
Full URL or path to navigate after requesting phone verification.
- Name
transferable?
- Type
boolean
- Description
Indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to
true
. When set tofalse
, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist. See OAuth account transfer flows for more information.
Example
See the custom flow guide for a comprehensive example of how to use the handleRedirectCallback()
method.
handleUnauthenticated()
Handles a 401 response from Frontend API by refreshing the client and session object accordingly.
function handleUnauthenticated(opts?: { broadcast: boolean }): Promise<unknown>
await clerk.handleUnauthenticated()
joinWaitlist()
Create a new waitlist entry programatically. Requires that you set your app's sign-up mode to Waitlist in the Clerk Dashboard.
function joinWaitlist({ emailAddress }: JoinWaitlistParams): Promise<Waitlist>
- Name
emailAddress
- Type
string
- Description
The email address of the user you want to add in the waitlist.
await clerk.joinWaitlist({ emailAddress: 'user@example.com' })
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
All props below are optional.
- Name
appearance
- Type
Appearance | undefined
- Description
Optional object to style your components. Will only affect Clerk components and not Account Portal pages.
- Name
localization
- Type
Localization | undefined
- Description
Optional object to localize your components. Will only affect Clerk components and not Account Portal 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) => 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.
await clerk.load()
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 await
ed 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): Promise<unknown>
await clerk.navigate('/dashboard')
- Name
to
- Type
string | undefined
- Description
The route to navigate to.
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 await
ed 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>
await clerk.redirectToCreateOrganization()
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 await
ed 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>
await clerk.redirectToOrganizationProfile()
redirectToSignIn()
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 await
ed 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>
- Name
options?
- Type
SignInRedirectOptions | undefined
- Description
Options to use in the redirect, such as
signInForceRedirectUrl
andsignInFallbackRedirectUrl
.
await clerk.redirectToSignIn({
signInForceRedirectUrl: '/dashboard',
signUpForceRedirectUrl: '/dashboard',
})
redirectToSignUp()
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 await
ed 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>
- Name
options?
- Type
SignUpRedirectOptions | undefined
- Description
Options to use in the redirect, such as
signUpForceRedirectUrl
andsignUpFallbackRedirectUrl
.
await clerk.redirectToSignUp({
signUpForceRedirectUrl: '/dashboard',
signUpFallbackRedirectUrl: '/dashboard',
})
redirectToUserProfile()
Returns a promise that can be await
ed 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>
await clerk.redirectToUserProfile()
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 await
ed 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>
- Name
to
- Type
string | undefined
- Description
The route to navigate to
await clerk.redirectWithAuth('/dashboard')
setActive()
A method used to set the active session and/or organization. Accepts a SetActiveParams
object.
function setActive(params: SetActiveParams): Promise<void>
Example
The setActive()
method is most commonly used when building a custom flow for your application.
For example, during authentication, when a user signs in or signs up successfully, a new session is created. setActive()
needs to be used to set the new session as the active session. See the implementation of this in the Custom authentication flow guide.
Another example is when a user switches organizations in a multi-organization application. setActive()
needs to be used to set the new organization as the active organization. See the implementation of this in the Custom organization switcher guide.
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>
- 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.
await clerk.signOut()
Components
The Clerk
class also contains a number of methods for interacting with prebuilt components.
<SignIn />
<SignUp />
<GoogleOneTap />
<UserButton />
<UserProfile />
<OrganizationProfile />
mountOrganizationProfile()
unmountOrganizationProfile()
openOrganizationProfile()
closeOrganizationProfile()
<OrganizationSwitcher />
<CreateOrganization />
<OrganizationList />
<Waitlist />
Feedback
Last updated on