# Clerk class
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()](https://clerk.com/docs/react-router/reference/hooks/use-clerk.md) hook to access the `clerk` object. The `clerk` object is used to call the [openSignIn()](https://clerk.com/docs/react-router/reference/objects/clerk.md#sign-in) method to open the sign-in modal.
filename: app/routes/home.tsx
```tsx
import { useClerk } from '@clerk/react-router'
export default function Home() {
const clerk = useClerk()
return
}
```
## Properties
| Property | Type | Description |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKeys` | [APIKeysNamespace](https://clerk.com/docs/react-router/reference/objects/api-keys.md) | The `APIKeys` object used for managing API keys. |
| `billing` | [BillingNamespace](https://clerk.com/docs/react-router/reference/objects/billing.md) | The `Billing` object used for managing billing. |
| `client` | undefined | ClientResource | The `Client` object for the current window. |
| `domain` | `string` | The current Clerk app's domain. Prefixed with `clerk.` on production if not already prefixed. Returns `""` when ran on the server. |
| `instanceType` | `undefined | "production" | "development"` | Indicates whether the Clerk instance is running in a production or development environment. |
| `isSatellite` | `boolean` | Indicates whether the instance is a satellite app. |
| `isSignedIn` | `boolean` | Indicates whether the current user has a valid signed-in client session. |
| `isStandardBrowser` | `undefined | boolean` | 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. |
| `loaded` | `boolean` | 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"`. |
| `oauthApplication` | [`OAuthApplicationNamespace`](../o-auth-application-namespace.mdx) | OAuth application helpers (e.g. consent metadata for custom consent UIs). |
| `organization` | undefined | null | OrganizationResource | 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. |
| `proxyUrl` | `undefined | string` | **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:///__clerk`). |
| `publishableKey` | `string` | Your Clerk Publishable Key. |
| `sdkMetadata` | `undefined | { environment?: string; name: string; version: string; }` | 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](https://clerk.com/docs/guides/development/sdk-development/overview.md?sdk=react-router). |
| `session` | undefined | null | SignedInSessionResource | 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`. |
| `status` | `"error" | "degraded" | "loading" | "ready"` | 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.
|
| `telemetry` | `undefined | { isDebug: boolean; isEnabled: boolean; record: void; recordLog: void; }` | [Telemetry](https://clerk.com/docs/guides/how-clerk-works/security/clerk-telemetry.md?sdk=react-router) configuration. |
| `user` | undefined | null | UserResource | A shortcut to `Session.user` which holds the currently active `User` object. If the session is `null` or `undefined`, the user field will match. |
| `version` | `undefined | string` | The Clerk SDK version number. |
## Methods
### `addListener()`
Register a listener that triggers a callback whenever a change in the [Client](https://clerk.com/docs/react-router/reference/objects/client.md), [Session](https://clerk.com/docs/react-router/reference/objects/session.md), [User](https://clerk.com/docs/react-router/reference/objects/user.md), or [Organization](https://clerk.com/docs/react-router/reference/objects/organization.md) resources occurs. This method is primarily used to build frontend SDKs like [`@clerk/react`](https://www.npmjs.com/package/@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.
```typescript
function addListener(callback: (emission: { client: ClientResource; organization?: null | OrganizationResource; session?: null | SignedInSessionResource; user?: null | UserResource }) => void, options?: { skipInitialEmit?: boolean }): UnsubscribeCallback
```
#### Parameters
| Parameter | Type | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `callback` | (emission: { client: ClientResource; organization?: null | OrganizationResource; session?: null | SignedInSessionResource; user?: null | UserResource; }) => void | The function to call when Clerk resources change. |
| `options?` | `{ skipInitialEmit?: boolean; }` | Optional configuration. |
| `options?.skipInitialEmit?` | `boolean` | 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.
```typescript
function authenticateWithBase(params?: AuthenticateWithBaseParams): Promise
```
#### `AuthenticateWithBaseParams`
| Property | Type | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNavigate?` | (to: string) => Promise | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `redirectUrl?` | `string` | The full URL or path to navigate to after a successful sign-in or sign-up. |
| `signUpContinueUrl?` | `string` | The URL to navigate to if the sign-up process is missing user information. |
| `unsafeMetadata?` | [SignUpUnsafeMetadata](https://clerk.com/docs/react-router/reference/types/metadata.md#sign-up-unsafe-metadata) | 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.
```typescript
function authenticateWithCoinbaseWallet(params?: AuthenticateWithCoinbaseWalletParams): Promise
```
#### `AuthenticateWithCoinbaseWalletParams`
| Property | Type | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNavigate?` | (to: string) => Promise | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `redirectUrl?` | `string` | The full URL or path to navigate to after a successful sign-in or sign-up. |
| `signUpContinueUrl?` | `string` | The URL to navigate to if the sign-up process is missing user information. |
| `unsafeMetadata?` | [SignUpUnsafeMetadata](https://clerk.com/docs/react-router/reference/types/metadata.md#sign-up-unsafe-metadata) | 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.
```typescript
function authenticateWithGoogleOneTap(params: AuthenticateWithGoogleOneTapParams): Promise
```
#### `AuthenticateWithGoogleOneTapParams`
| Property | Type | Description |
| ------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `token` | `string` | 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.
```typescript
function authenticateWithMetamask(params?: AuthenticateWithMetamaskParams): Promise
```
#### `AuthenticateWithMetamaskParams`
| Property | Type | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNavigate?` | (to: string) => Promise | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `redirectUrl?` | `string` | The full URL or path to navigate to after a successful sign-in or sign-up. |
| `signUpContinueUrl?` | `string` | The URL to navigate to if the sign-up process is missing user information. |
| `unsafeMetadata?` | [SignUpUnsafeMetadata](https://clerk.com/docs/react-router/reference/types/metadata.md#sign-up-unsafe-metadata) | 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.
```typescript
function authenticateWithOKXWallet(params?: AuthenticateWithOKXWalletParams): Promise
```
#### `AuthenticateWithOKXWalletParams`
| Property | Type | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNavigate?` | (to: string) => Promise | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `redirectUrl?` | `string` | The full URL or path to navigate to after a successful sign-in or sign-up. |
| `signUpContinueUrl?` | `string` | The URL to navigate to if the sign-up process is missing user information. |
| `unsafeMetadata?` | [SignUpUnsafeMetadata](https://clerk.com/docs/react-router/reference/types/metadata.md#sign-up-unsafe-metadata) | 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.
```typescript
function authenticateWithSolana(params: AuthenticateWithSolanaParams): Promise
```
#### `AuthenticateWithSolanaParams`
| Property | Type | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNavigate?` | (to: string) => Promise | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `redirectUrl?` | `string` | The full URL or path to navigate to after a successful sign-in or sign-up. |
| `signUpContinueUrl?` | `string` | The URL to navigate to if the sign-up process is missing user information. |
| `unsafeMetadata?` | [SignUpUnsafeMetadata](https://clerk.com/docs/react-router/reference/types/metadata.md#sign-up-unsafe-metadata) | 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. |
| `walletName` | `string` | 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.
```typescript
function authenticateWithWeb3(params: ClerkAuthenticateWithWeb3Params): Promise
```
#### `ClerkAuthenticateWithWeb3Params`
| Property | Type | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customNavigate?` | (to: string) => Promise | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |
| `legalAccepted?` | `boolean` | A boolean indicating whether the user has agreed to the [legal compliance](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=react-router) documents. |
| `redirectUrl?` | `string` | The full URL or path to navigate to after a successful sign-in or sign-up. |
| `secondFactorUrl?` | `string` | The URL to navigate to if [second factor](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=react-router#multi-factor-authentication) is required. |
| `signUpContinueUrl?` | `string` | The URL to navigate to if the sign-up process is missing user information. |
| `strategy` | `"web3_metamask_signature" | "web3_base_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_signature" | "web3_solana_signature"` | The strategy to use for the sign-in flow. |
| `unsafeMetadata?` | [SignUpUnsafeMetadata](https://clerk.com/docs/react-router/reference/types/metadata.md#sign-up-unsafe-metadata) | 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. |
| `walletName?` | `string` | The name of the wallet to use for authentication. |
### `buildAfterMultiSessionSingleSignOutUrl()`
Returns the configured `afterMultiSessionSingleSignOutUrl` of the instance.
```typescript
function buildAfterMultiSessionSingleSignOutUrl(): string
```
### `buildAfterSignInUrl()`
Returns the configured `afterSignInUrl` of the instance.
```typescript
function buildAfterSignInUrl(params?: { params?: URLSearchParams }): string
```
#### Parameters
| Parameter | Type | Description |
| --------- | ------------------------------------------ | ----------------------------------------------- |
| `params?` | `{ params?: URLSearchParams; }` | Optional query parameters to append to the URL. |
### `buildAfterSignOutUrl()`
Returns the configured `afterSignOutUrl` of the instance.
```typescript
function buildAfterSignOutUrl(): string
```
### `buildAfterSignUpUrl()`
Returns the configured `afterSignUpUrl` of the instance.
```typescript
function buildAfterSignUpUrl(params?: { params?: URLSearchParams }): string
```
#### Parameters
| Parameter | Type | Description |
| --------- | ------------------------------------------ | ----------------------------------------------- |
| `params?` | `{ params?: URLSearchParams; }` | Optional query parameters to append to the URL. |
### `buildCreateOrganizationUrl()`
Returns the configured URL where [](https://clerk.com/docs/react-router/reference/components/organization/create-organization.md) is mounted or a custom create-organization page is rendered.
```typescript
function buildCreateOrganizationUrl(): string
```
### `buildNewSubscriptionRedirectUrl()`
Returns the configured `newSubscriptionRedirectUrl` of the instance.
```typescript
function buildNewSubscriptionRedirectUrl(): string
```
### `buildOrganizationProfileUrl()`
Returns the configured URL where [](https://clerk.com/docs/react-router/reference/components/organization/organization-profile.md) is mounted or a custom organization-profile page is rendered.
```typescript
function buildOrganizationProfileUrl(): string
```
### `buildSignInUrl()`
Returns the configured URL where [](https://clerk.com/docs/react-router/reference/components/authentication/sign-in.md) is mounted or a custom sign-in page is rendered.
```typescript
function buildSignInUrl(opts?: RedirectOptions): string
```
#### `RedirectOptions`
| Property | Type | Description |
| ------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `redirectUrl?` | `string | null` | Full URL or path to navigate to after a successful action. |
| `signInFallbackRedirectUrl?` | `string | null` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. Defaults to `'/'`. |
| `signInForceRedirectUrl?` | `string | null` | If provided, this URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
| `signUpFallbackRedirectUrl?` | `string | null` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. Defaults to `'/'`. |
| `signUpForceRedirectUrl?` | `string | null` | If provided, this URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
### `buildSignUpUrl()`
Returns the configured URL where [](https://clerk.com/docs/react-router/reference/components/authentication/sign-up.md) is mounted or a custom sign-up page is rendered.
```typescript
function buildSignUpUrl(opts?: RedirectOptions): string
```
#### `RedirectOptions`
| Property | Type | Description |
| ------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `redirectUrl?` | `string | null` | Full URL or path to navigate to after a successful action. |
| `signInFallbackRedirectUrl?` | `string | null` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. Defaults to `'/'`. |
| `signInForceRedirectUrl?` | `string | null` | If provided, this URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
| `signUpFallbackRedirectUrl?` | `string | null` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. Defaults to `'/'`. |
| `signUpForceRedirectUrl?` | `string | null` | If provided, this URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
### `buildTasksUrl()`
Returns the configured URL where [session tasks](https://clerk.com/docs/guides/configure/session-tasks.md?sdk=react-router) are mounted.
```typescript
function buildTasksUrl(): string
```
### `buildUrlWithAuth()`
Decorates the provided URL with the auth token for development instances.
```typescript
function buildUrlWithAuth(to: string): string
```
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------- |
| `to` | `string` | The route to create a URL towards. |
### `buildUserProfileUrl()`
Returns the configured URL where [](https://clerk.com/docs/react-router/reference/components/user/user-profile.md) is mounted or a custom user-profile page is rendered.
```typescript
function buildUserProfileUrl(): string
```
### `buildWaitlistUrl()`
Returns the configured URL where [](https://clerk.com/docs/react-router/reference/components/authentication/waitlist.md) is mounted or a custom waitlist page is rendered.
```typescript
function buildWaitlistUrl(opts?: { initialValues?: Record }): string
```
#### Parameters
| Parameter | Type | Description |
| ---------------------- | -------------------------------------------------------- | -------------------------------------------- |
| `opts?` | { initialValues?: Record; } | Options to control the waitlist URL. |
| `opts?.initialValues?` | `Record`<`string`, `string`> | Initial values to prefill the waitlist form. |
### `createOrganization()`
Creates an Organization programmatically, adding the current user as admin. Returns an [Organization](https://clerk.com/docs/react-router/reference/objects/organization.md) object.
> For React-based apps, consider using the [](https://clerk.com/docs/react-router/reference/components/organization/create-organization.md) component.
```typescript
function createOrganization(params: CreateOrganizationParams): Promise
```
#### `CreateOrganizationParams`
| Property | Type | Description |
| ------------------------- | -------- | ----------------------------- |
| `name` | `string` | The name of the Organization. |
| `slug?` | `string` | The slug of the Organization. |
### `getOrganization()`
Gets a single [Organization](https://clerk.com/docs/react-router/reference/objects/organization.md) by ID.
```typescript
function getOrganization(organizationId: string): Promise
```
#### Parameters
| Parameter | Type | Description |
| ---------------- | -------- | ---------------------------------- |
| `organizationId` | `string` | 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.
```typescript
function handleEmailLinkVerification(params: { onVerifiedOnOtherDevice?: () => void; redirectUrl?: string; redirectUrlComplete?: string }, customNavigate?: (to: string) => Promise): Promise
```
#### Parameters
| Parameter | Type | Description |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params` | `{ onVerifiedOnOtherDevice?: () => void; redirectUrl?: string; redirectUrlComplete?: string; }` | 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. |
| `params.onVerifiedOnOtherDevice?` | `() => void` | Callback function to be executed after successful email link verification on another device. |
| `params.redirectUrl?` | `string` | The full URL to navigate to after successful email link verification on the same device, but without completing sign-in or sign-up. |
| `params.redirectUrlComplete?` | `string` | The full URL to navigate to after successful email link verification on completed sign-up or sign-in on the same device. |
| `customNavigate?` | (to: string) => Promise | 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](https://clerk.com/docs/guides/secure/best-practices/protect-email-links.md?sdk=react-router) 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](https://clerk.com/docs/react-router/reference/objects/client.md#properties).
The method handles the verification outcome as follows:
1. 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.
2. On verification failure:
- Throws an [EmailLinkError](https://clerk.com/docs/react-router/guides/development/custom-flows/authentication/email-links.md).
- 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()](https://clerk.com/docs/react-router/reference/objects/clerk.md#authenticate-with-google-one-tap). This method should be called after the user is redirected back from visiting the Google One Tap prompt.
```typescript
function handleGoogleOneTapCallback(signInOrUp: SignInResource | SignUpResource, params: HandleOAuthCallbackParams, customNavigate?: (to: string) => Promise): Promise
```
#### Parameters
| Parameter | Type | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `signInOrUp` | SignInResource | SignUpResource | The resource returned from the initial `authenticateWithGoogleOneTap()` call (before redirect). |
| `params` | [HandleOAuthCallbackParams](https://clerk.com/docs/react-router/reference/types/handle-o-auth-callback-params.md) | Additional props that define where the user will be redirected to at the end of a successful Google One Tap flow. |
| `customNavigate?` | (to: string) => Promise | 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)](https://clerk.com/docs/react-router/reference/objects/sign-in.md) or [SignUp.authenticateWithRedirect(params)](https://clerk.com/docs/react-router/reference/objects/sign-up.md).
```typescript
function handleRedirectCallback(params: HandleOAuthCallbackParams, customNavigate?: (to: string) => Promise): Promise
```
#### Parameters
| Parameter | Type | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `params` | [HandleOAuthCallbackParams](https://clerk.com/docs/react-router/reference/types/handle-o-auth-callback-params.md) | Additional props that define where the user will be redirected to at the end of a successful OAuth or SAML flow. |
| `customNavigate?` | (to: string) => Promise | 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](https://clerk.com/docs/guides/development/custom-flows/authentication/oauth-connections.md?sdk=react-router) 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](https://clerk.com/docs/react-router/reference/objects/client.md) and [Session](https://clerk.com/docs/react-router/reference/objects/session.md) object accordingly.
```typescript
function handleUnauthenticated(): Promise
```
### `joinWaitlist()`
Create a new waitlist entry programmatically. Requires that you set your app's sign-up mode to [**Waitlist**](https://clerk.com/docs/guides/secure/restricting-access.md?sdk=react-router#waitlist) in the Clerk Dashboard.
```typescript
function joinWaitlist(params: JoinWaitlistParams): Promise
```
#### `JoinWaitlistParams`
| Property | Type | Description |
| ---------------------------------------- | -------- | ----------------------------------------------------- |
| `emailAddress` | `string` | 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](https://clerk.com/docs/reference/frontend-api){{ target: '_blank' }}.
```typescript
function load(opts?: Without): Promise
```
#### `ClerkOptions`
The `load()` method accepts an optional object that accepts the following props. All props are optional.
| Name | Type | Description |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `afterMultiSessionSingleSignOutUrl?` | `string | null` | The full URL or path to navigate to after signing out the current user is complete. This option applies to [multi-session applications](https://clerk.com/docs/guides/secure/session-options.md?sdk=react-router#multi-session-applications). |
| `afterSignOutUrl?` | `string | null` | The full URL or path to navigate to after successful sign out. |
| `allowedRedirectOrigins?` | `(string | RegExp)[]` | 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. |
| `allowedRedirectProtocols?` | `string[]` | 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. |
| `appearance?` | `any` | An object to style your components. Will only affect [Clerk Components](https://clerk.com/docs/react-router/reference/components/overview.md) and not [Account Portal](https://clerk.com/docs/guides/account-portal/overview.md?sdk=react-router) pages. See the [Appearance](https://clerk.com/docs/react-router/guides/customizing-clerk/appearance-prop/overview.md) docs for more information. |
| `experimental?` | `Autocomplete`<`{ commerce: boolean; persistClient: boolean; rethrowOfflineNetworkErrors: boolean; runtimeEnvironment: "headless"; }`, `Record`<`string`, `any`>> | 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. |
| `isSatellite?` | `boolean | (url: URL) => boolean` | Indicates whether the application is a satellite application. |
| `localization?` | [`LocalizationResource`](https://clerk.com/docs/guides/customizing-clerk/localization.md?sdk=react-router) | An object to localize your components. Will only affect [Clerk Components](https://clerk.com/docs/react-router/reference/components/overview.md) and not [Account Portal](https://clerk.com/docs/guides/account-portal/overview.md?sdk=react-router) pages. |
| `newSubscriptionRedirectUrl?` | `string | null` | The full URL or path to navigate to after the user completes the checkout and clicks the "Continue" button. |
| `polling?` | `boolean` | Indicates whether Clerk should poll against Clerk's backend every 5 minutes. Defaults to `true`. |
| `routerDebug?` | `boolean` | If `true`, the router will log debug information to the console. |
| `routerPush()` | `(to: string, metadata?: { windowNavigate: (to: URL | string) => void; }) => unknown` | A function which takes the destination path as an argument and performs a "push" navigation. |
| `routerReplace()` | `(to: string, metadata?: { windowNavigate: (to: URL | string) => void; }) => unknown` | A function which takes the destination path as an argument and performs a "replace" navigation. |
| `satelliteAutoSync?` | `boolean` | 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`. |
| `sdkMetadata?` | `{ environment?: string; name: string; version: string; }` | 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](https://clerk.com/docs/guides/development/sdk-development/overview.md?sdk=react-router). |
| `sdkMetadata.environment?` | `string` | Typically this will be the `NODE_ENV` that the SDK is currently running in. |
| `sdkMetadata.name` | `string` | The npm package name of the SDK. |
| `sdkMetadata.version` | `string` | The npm package version of the SDK. |
| `selectInitialSession()?` | (client: ClientResource) => SignedInSessionResource | null | 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. |
| `signInFallbackRedirectUrl?` | `string | null` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. Defaults to `'/'`. |
| `signInForceRedirectUrl?` | `string | null` | If provided, this URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
| `signInUrl?` | `string` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
| `signUpFallbackRedirectUrl?` | `string | null` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. Defaults to `'/'`. |
| `signUpForceRedirectUrl?` | `string | null` | If provided, this URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
| `signUpUrl?` | `string` | 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](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=react-router#sign-in-and-sign-up-redirects) instead. |
| `standardBrowser?` | `boolean` | 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`. |
| `supportEmail?` | `string` | The support email address for display in authentication screens. Will only affect [Clerk Components](https://clerk.com/docs/react-router/reference/components/overview.md) and not [Account Portal](https://clerk.com/docs/guides/account-portal/overview.md?sdk=react-router) pages. |
| `taskUrls?` | `Partial`<`Record`<[SessionTask](https://clerk.com/docs/react-router/reference/types/session-task.md)[`"key"`], `string`>> | 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`. |
| `telemetry?` | `false | { debug?: boolean; disabled?: boolean; perEventSampling?: boolean; }` | Controls whether or not Clerk will collect [telemetry data](https://clerk.com/docs/guides/how-clerk-works/security/clerk-telemetry.md?sdk=react-router). If set to `debug`, telemetry events are only logged to the console and not sent to Clerk. |
| `telemetry.debug?` | `boolean` | If `true`, telemetry events are only logged to the console and not sent to Clerk |
| `telemetry.disabled?` | `boolean` | If `true`, telemetry will not be collected. |
| `telemetry.perEventSampling?` | `boolean` | If false, the sampling rates provided per telemetry event will be ignored and all events will be sent. Defaults to `true`. |
| `touchSession?` | `boolean` | By default, the [Clerk Frontend API `touch` endpoint](https://clerk.com/docs/reference/frontend-api/tag/Sessions#operation/touchSession){{ target: '_blank' }} is called during page focus to keep the last active session alive. This option allows you to disable this behavior. |
| `ui?` | { ClerkUI?: ClerkUIConstructor | Promise; } | **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. |
| `ui.ClerkUI?` | ClerkUIConstructor | Promise | Pass the `ui` export from `@clerk/ui`. |
| `waitlistUrl?` | `string` | The full URL or path to the waitlist page. If `undefined`, will redirect to the [Account Portal waitlist page](https://clerk.com/docs/guides/account-portal/overview.md?sdk=react-router#waitlist). |
### `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.
```typescript
function navigate(to: string, options?: { metadata?: RouterMetadata; replace?: boolean }): Promise | void
```
#### Parameters
| Parameter | Type | Description |
| -------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `to` | `string` | The URL or relative path to navigate to. |
| `options?` | `{ metadata?: RouterMetadata; replace?: boolean; }` | Optional configuration. |
| `options?.metadata?` | `RouterMetadata` | Router metadata. |
| `options?.replace?` | `boolean` | If `true`, replace the current history entry instead of pushing a new one. |
### `off()`
Removes an event handler for a specific Clerk event.
```typescript
function off(event: E, handler: EventHandler): void
```
#### Parameters
| Parameter | Type | Description |
| --------- | -------------------- | ----------------------------------- |
| `event` | `E` | The event name to unsubscribe from. |
| `handler` | `EventHandler`<`E`> | The callback function to remove. |
### `on()`
Registers an event handler for a specific Clerk event.
```typescript
function on(event: E, handler: EventHandler, opt?: { notify: boolean }): void
```
#### Parameters
| Parameter | Type | Description |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `event` | `E` | The event name to subscribe to. |
| `handler` | `EventHandler`<`E`> | The callback function to execute when the event is dispatched. |
| `opt?` | `{ notify: boolean; }` | Optional configuration. |
| `opt?.notify?` | `boolean` | If true and the event was previously dispatched, handler will be called immediately with the latest payload. |
### `redirectToAfterSignIn()`
Redirects to the configured `afterSignIn` URL.
```typescript
function redirectToAfterSignIn(): void
```
### `redirectToAfterSignOut()`
Redirects to the configured `afterSignOut` URL.
```typescript
function redirectToAfterSignOut(): void
```
### `redirectToCreateOrganization()`
Redirects to the configured URL where [](https://clerk.com/docs/react-router/reference/components/organization/create-organization.md) is mounted. This method uses the [navigate()](https://clerk.com/docs/react-router/reference/objects/clerk.md#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.
```typescript
function redirectToCreateOrganization(): Promise
```
### `redirectToOrganizationProfile()`
Redirects to the configured URL where [](https://clerk.com/docs/react-router/reference/components/organization/organization-profile.md) is mounted. This method uses the [navigate()](https://clerk.com/docs/react-router/reference/objects/clerk.md#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.
```typescript
function redirectToOrganizationProfile(): Promise
```
### `redirectToSignIn()`
Redirects to the sign-in URL, as configured in your application's instance settings. This method uses the [navigate()](https://clerk.com/docs/react-router/reference/objects/clerk.md#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.
```typescript
function redirectToSignIn(opts?: SignInRedirectOptions): Promise
```
#### Parameters
| Parameter | Type | Description |
| --------- | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `opts?` | [SignInRedirectOptions](https://clerk.com/docs/react-router/reference/types/sign-in-redirect-options.md) | 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()](https://clerk.com/docs/react-router/reference/objects/clerk.md#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.
```typescript
function redirectToSignUp(opts?: SignUpRedirectOptions): Promise
```
#### Parameters
| Parameter | Type | Description |
| --------- | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `opts?` | [SignUpRedirectOptions](https://clerk.com/docs/react-router/reference/types/sign-up-redirect-options.md) | Options to control the redirect. |
### `redirectToTasks()`
Redirects to the configured URL where [session tasks](https://clerk.com/docs/react-router/reference/objects/session.md) are mounted.
```typescript
function redirectToTasks(opts?: TasksRedirectOptions): Promise
```
#### Parameters
| Parameter | Type | Description |
| --------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `opts?` | [TasksRedirectOptions](https://clerk.com/docs/react-router/reference/types/redirect-options.md) | Options to control the redirect (e.g. redirect URL after tasks are complete). |
### `redirectToUserProfile()`
Redirects to the configured URL where [](https://clerk.com/docs/react-router/reference/components/user/user-profile.md) is mounted.
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.
```typescript
function redirectToUserProfile(): Promise
```
### `redirectToWaitlist()`
Redirects to the configured URL where [](https://clerk.com/docs/react-router/reference/components/authentication/waitlist.md) is mounted.
```typescript
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 `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.
```typescript
function redirectWithAuth(to: string): Promise
```
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | ----------------------- |
| `to` | `string` | The URL to redirect to. |
### `setActive()`
A method used to set the current session and/or Organization for the client. Accepts a [SetActiveParams](https://clerk.com/docs/react-router/reference/types/set-active-params.md) 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.
```typescript
function setActive(setActiveParams: SetActiveParams): Promise
```
#### `SetActiveParams`
| Property | Type | Description |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `navigate?` | `SetActiveNavigate` | 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](https://clerk.com/docs/react-router/reference/objects/clerk.md#using-the-navigate-parameter) for more details. |
| `organization?` | null | string | OrganizationResource | 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. |
| `redirectUrl?` | `string` | The full URL or path to redirect to just before the session and/or organization is set. |
| `session?` | null | string | SignedInSessionResource | 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:
```typescript
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.
> 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.
```typescript
function signOut(options?: SignOutOptions): Promise
```
#### `SignOutOptions`
| Property | Type | Description |
| --------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `redirectUrl?` | `string` | Specify a redirect URL to navigate to after sign-out is complete. |
| `sessionId?` | `string` | Specify a specific session to sign out. Useful for multi-session applications. |
---
## Sitemap
[Overview of all docs pages](https://clerk.com/docs/llms.txt)