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
params- Type
HandleMagicLinkVerificationParams- 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 magic 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 magic 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 magic 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 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
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.
- Name
afterSignUpUrl- Type
string | undefined | null- Description
Full URL or path to navigate after successful sign up.
- Name
afterSignInUrl- Type
string | undefined | null- Description
Full URL or path to navigate after successful sign in.
- Name
redirectUrl- Type
string | undefined | null- Description
Full URL or path to navigate after successful sign in or sign up.
The same as settingafterSignInUrlandafterSignUpUrlto the same value.
- 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.
function handleUnauthenticated(opts?: { broadcast: boolean }): Promise<unknown>;Handles a 401 response from Frontend API by refreshing the client and session object accordingly.
Feedback
Last updated on