Skip to content
Alchemy Logo

Email Magic Link Authentication

Email magic link authentication is a two-step process:

  1. The user enters their email address and requests a magic link
  2. The user clicks the link in their email, which redirects them back to your application to complete authentication

Email OTP has been shown to have up to a 3x higher conversion rate and a 10-second faster flow compared to magic links. Consider using Email OTP for better user experience.

You can implement Email Magic Link authentication in two ways:

Smart Wallets provides pre-built UI components that handle the entire Email Magic Link authentication flow with minimal code.

Before configuring your authentication, first add one of the pre-built components to your application:

To add authentication in a modal popup:

import React from "react";
import { useAuthModal } from "@account-kit/react";
 
export default function MyPage() {
  const { openAuthModal } = useAuthModal();
 
  return <button onClick={openAuthModal}>Sign in</button>;
}

For more details on modal configuration, see the Modal Authentication documentation.

Or:

To embed authentication directly in your page:

import React from "react";
import { AuthCard } from "@account-kit/react";
 
export default function MyLoginPage() {
  return (
    <div className="flex flex-row p-4 bg-white border border-gray-200 rounded-lg">
      <AuthCard />
    </div>
  );
}

For more details on embedded authentication, see the Embedded Authentication documentation.

After adding the components, configure the Email Magic Link authentication in your application config:

import { AlchemyAccountsUIConfig, createConfig } from "@account-kit/react";
import { sepolia, alchemy } from "@account-kit/infra";
 
const uiConfig: AlchemyAccountsUIConfig = {
  auth: {
    sections: [
      [
        {
          type: "email",
          emailMode: "magicLink",
 
          // Optional customizations:
          buttonLabel: "Continue with Email",
          placeholder: "Enter your email address",
        },
      ],
    ],
  },
};
 
export const config = createConfig(
  {
    transport: alchemy({ apiKey: "your-api-key" }),
    chain: sepolia,
  },
  uiConfig,
);

If you need complete control over the user experience, you can implement your own custom UI for Email Magic Link authentication using Smart Wallets hooks.

First, prompt your user for their email address and send a magic link:

import { useAuthenticate } from "@account-kit/react";
 
// Inside your component
const { authenticate } = useAuthenticate();
 
// When the user submits their email
const handleSendMagicLink = (email: string) => {
  authenticate(
    {
      type: "email",
      emailMode: "magicLink",
      email,
    },
    {
      onSuccess: () => {
        // onSuccess only fires once the entire flow is done (email magic link + optional MFA).
        // It still runs even if the final step completes in another tab/window.
      },
      onError: (error) => {
        // Handle error
      },
    },
  );
};

When the user clicks the magic link in their email, they'll be redirected back to your application. You need to extract the authentication bundle from the URL and complete the authentication:

import { useEffect } from "react";
import { useAuthenticate } from "@account-kit/react";
 
// Inside your component
const { authenticate } = useAuthenticate();
 
// Handle the redirect when the component mounts
useEffect(() => {
  const handleRedirect = () => {
    const url = new URL(window.location.href);
    const bundle = url.searchParams.get("bundle");
 
    if (bundle) {
      authenticate(
        {
          type: "email",
          bundle,
        },
        {
          onSuccess: () => {
            // onSuccess only fires once the entire flow is done (email magic link + optional MFA).
            // It still runs even if the final step completes in another tab/window.
          },
          onError: (error) => {
            // Handle error
          },
        },
      );
    }
  };
 
  handleRedirect();
}, [authenticate]);

Use the useSignerStatus hook to determine if the user is authenticated:

import { useSignerStatus } from "@account-kit/react";
 
// Inside your component
const { isConnected } = useSignerStatus();
 
// You can use isConnected to conditionally render UI

Consider enabling Multi-Factor Authentication to require users to enter a 6-digit TOTP code from their authenticator app after clicking the magic link. This extra layer of security protects user accounts if their email is compromised.

Was this page helpful?