`useMagicLinkVerification()` hook

useMagicLinkVerification() is the headless verification hook behind <MagicLinkVerification />. It verifies the callback token and attempt pair, tracks whether verification is still running, and exposes a simple success state for the page that owns the redirect after verification completes.

Usage

The following example shows a basic usage of useMagicLinkVerification().

export default function MagicLinkPage() {  const { loading, success, verifyMagicLink } = useMagicLinkVerification();  async function verify() {    await verifyMagicLink({      token: 'magic-link-token',      attempt: 'signin-attempt-id',      redirectUri: window.location.href,    });  }  return (    <div>      <button onClick={verify}>Verify magic link</button>      {loading ? <p>Verifying…</p> : null}      {success === true ? <p>Verified.</p> : null}    </div>  );}

Return value

The hook returns the following fields and methods.

›

loading: boolean;

Whether the hook is still waiting for the shared client or is currently verifying the magic link.

›

verifyMagicLink: (params: { token?: string; attempt?: string; redirectUri?: string }) => Promise<ApiResult<{}>>;

Verifies a magic-link token and the associated attempt identifier.

›

token?: string | undefined | undefined;

Magic-link token returned in the callback URL.

›

attempt?: string | undefined | undefined;

Sign-in attempt identifier returned in the callback URL.

›

redirectUri?: string | undefined | undefined;

Optional redirect target to carry through the verification request.

›

success: boolean | null;

Verification outcome. `null` means the current request has not finished yet, `true` means verification succeeded, and `false` means the last verification attempt failed.

How it works

The hook only owns the verification request and the small bit of state around it. It does not read query params on its own and it does not navigate after success.

The stock <MagicLinkVerification /> component reads the callback token, attempt, and redirect target from the current URL, then passes those values into this hook.

When verifyMagicLink() starts, the hook resets success back to null, marks itself loading, and then updates success to true or false when the request finishes.

If either token or attempt is missing, the hook throws before sending the verification request.

The hook is intentionally small so apps can decide what success and failure should look like, including whether to show a status page, redirect immediately, or let the user retry.

When to use it

Examples

Verify from the current callback URL

import { useEffect } from 'react';export default function MagicLinkCallbackPage() {  const { loading, success, verifyMagicLink } = useMagicLinkVerification();  useEffect(() => {    const params = new URLSearchParams(window.location.search);    const token = params.get('token') ?? undefined;    const attempt = params.get('attempt') ?? undefined;    const redirectUri = params.get('redirect_uri') ?? undefined;    if (!token || !attempt) {      return;    }    void verifyMagicLink({ token, attempt, redirectUri });  }, [verifyMagicLink]);  if (loading) {    return <p>Verifying your magic link…</p>;  }  if (success === false) {    return <p>This magic link is no longer valid.</p>;  }  return null;}

Retry verification from a custom screen

export default function RetryMagicLink() {  const { loading, success, verifyMagicLink } = useMagicLinkVerification();  async function retry() {    await verifyMagicLink({      token: 'magic-link-token',      attempt: 'signin-attempt-id',    });  }  return (    <div>      <button onClick={retry} disabled={loading}>        Try again      </button>      {success === false ? <p>Verification failed.</p> : null}    </div>  );}

useMagicLinkVerification() hook