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.

`handleMagicLinkVerification()`

Completes a magic link verification flow once we've reached the magic link results URL.


function handleMagicLinkVerification(
    params: HandleMagicLinkVerificationParams,
    customNavigate?: ((to: string) => Promise<unknown>) | undefined
): Promise<unknown>;

When users click on magic links they get redirected to the URL that was provided during magic 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 can take three values: verified, failed or expired.

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 magic 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.

Magic 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 magic link flow on their desktop browser, but click on the magic link from their mobile phone.

The handleMagicLinkVerification() method takes care of finalizing the magic 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.

Additionally, the handleMagicLinkVerification() method allows you to execute a callback if the successful verification happened on another device.

In case the magic link verification wasn't successful, the handleMagicLinkVerification() method will throw a MagicLinkError. You can check the error's code property to see if the magic link expired, or the verification simply failed.

Take a look at the function parameters description below for more usage details.

Properties

Name	Type	Description
`params`	`HandleMagicLinkVerificationParams`	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 magic link is successfully verified on another device, there's a callback function parameter that allows custom code execution.
`customNavigate?`	`(to: string) => Promise<unknown>`	Allows you to define a custom navigation function.

`HandleMagicLinkVerificationParams`

Name	Type	Description
`redirectUrlComplete?`	`string \| undefined`	Full URL or path to navigate after successful magic link verification on completed sign up or sign in on the same device.
`redirectUrl?`	`string \| undefined`	Full URL or path to navigate after successful magic link verification on the same device, but not completed sign in or sign up.
`onVerifiedOnOtherDevice?`	`() => void`	Callback function to be executed after successful magic link verification on another device.

Returns

Type	Description
`Promise<unknown>`	This method will throw a `MagicLinkError` if the magic link verification failed or the link expired. Check the error's `code` property for details.

`handleRedirectCallback()`


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

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

Properties

Name	Type	Description
`params`	`HandleOAuthCallbackParams`	Additional props that define where the user will be redirected to at the end of a successful OAuth flow.
`customNavigate`	`(to: string) => Promise<unknown>`	Allows you to define a custom navigation function.

`HandleOAuthCallbackParams`

Name	Type	Description
`afterSignUpUrl`	`string \| undefined \| null`	Full URL or path to navigate after successful sign up.
`afterSignInUrl`	`string \| undefined \| null`	Full URL or path to navigate after successful sign in.
`redirectUrl`	`string \| undefined \| null`	Full URL or path to navigate after successful sign in or sign up. The same as setting `afterSignInUrl` and `afterSignUpUrl` to the same value.
`firstFactorUrl`	`string \| undefined`	Full URL or path to navigate during sign in, if identifier verification is required.
`secondFactorUrl`	`string \| undefined`	Full URL or path to navigate during sign in, if 2FA is enabled.
`resetPasswordUrl`	`string`	Full URL or path to navigate during sign in, if the user is required to reset their password.
`continueSignUpUrl`	`string \| undefined \| null`	Full URL or path to navigate after an incomplete sign up.
`verifyEmailAddressUrl`	`string \| undefined \| null`	Full URL or path to navigate after requesting email verification.
`verifyPhoneNumberUrl`	`string \| undefined \| null`	Full URL or path to navigate after requesting phone verification.

`handleUnauthenticated()`


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

Handles a 401 response from Frontend API(opens in a new tab) by refreshing the client and session object accordingly.