Docs

Handle navigation

These are all methods on the Clerk class that help you handle navigation callbacks from Clerk, usually in conjunction with redirect methods or built URLs.

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 and:

    • Completed sign in or sign up attempt.
    • Pending sign in or sign up attempt.

    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

    Allows you to define a custom navigation function.

  • Name
    redirectUrlComplete?
    Type
    string | undefined
    Description

    Full URL or path to navigate after successful email link verification on completed sign up or sign in on the same device.

  • Name
    redirectUrl?
    Type
    string | undefined
    Description

    Full URL or path to navigate after successful email link verification on the same device, but not completed sign in or sign up.

  • Name
    onVerifiedOnOtherDevice?
    Type
    () => void
    Description

    Callback function to be executed after successful email link verification on another device.

handleRedirectCallback()

Completes a custom OAuth flow started by calling either SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params).

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

Parameters

  • Name
    params
    Type
    HandleOAuthCallbackParams
    Description

    Additional props that define where the user will be redirected to at the end of a successful OAuth flow.

  • Name
    customNavigate
    Type
    (to: string) => Promise<unknown>
    Description

    Allows you to define a custom navigation function.

HandleOAuthCallbackParams

  • 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 to false, 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.

handleUnauthenticated()

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

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

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on