Magic link

Magic link or email link is a way to authenticate users without a password. When a user enters their email, a link is sent to their email. When the user clicks on the link, they are authenticated.

Installation

import { betterAuth } from "better-auth";
import { magicLink } from "better-auth/plugins";  

export const auth = betterAuth({
    plugins: [
        magicLink({ 
            sendMagicLink: async ({ email, token, url, metadata }, ctx) => { 
                // send email to user
            } 
        }) 
    ]
})

import { createAuthClient } from "better-auth/client";
import { magicLinkClient } from "better-auth/client/plugins"; 

export const authClient = createAuthClient({
    plugins: [
        magicLinkClient() 
    ]
});

Usage

Sign In with Magic Link

To sign in with a magic link, you need to call signIn.magicLink with the user's email address. The sendMagicLink function is called to send the magic link to the user's email.

const { data, error } = await authClient.signIn.magicLink({    email: "user@email.com", // required, Email address to send the magic link.    name: "my-name", // User display name. Only used if the user is registering for the first time.    callbackURL: "/dashboard", // URL to redirect after magic link verification.    newUserCallbackURL: "/welcome", // URL to redirect after new user signup.    errorCallbackURL: "/error", // URL to redirect if an error happens on verification If only callbackURL is provided but without an `errorCallbackURL` then they will be redirected to the callbackURL with an `error` query parameter.    metadata: { inviteId: "123" }, // Additional metadata forwarded to the sendMagicLink callback.});

const data = await auth.api.signInMagicLink({    body: {        email: "user@email.com", // required, Email address to send the magic link.        name: "my-name", // User display name. Only used if the user is registering for the first time.        callbackURL: "/dashboard", // URL to redirect after magic link verification.        newUserCallbackURL: "/welcome", // URL to redirect after new user signup.        errorCallbackURL: "/error", // URL to redirect if an error happens on verification If only callbackURL is provided but without an `errorCallbackURL` then they will be redirected to the callbackURL with an `error` query parameter.        metadata: { inviteId: "123" }, // Additional metadata forwarded to the sendMagicLink callback.    },    // Pass the current request headers so Better Auth can read and set cookies.    headers: await headers(),});

Verify Magic Link

When you send the URL generated by the sendMagicLink function to a user, clicking the link will authenticate them and redirect them to the callbackURL specified in the signIn.magicLink function. If an error occurs, the user will be redirected to the callbackURL with an error query parameter.

If you want to handle the verification manually, (e.g, if you send the user a different URL), you can use the verify function.

const { data, error } = await authClient.magicLink.verify({    query: {        token: "123456", // required, Verification token.        callbackURL: "/dashboard", // URL to redirect after magic link verification, if not provided will return the session.        newUserCallbackURL: "/welcome", // URL to redirect after new user signup.        errorCallbackURL: "/error", // URL to redirect if an error happens on verification. If only callbackURL is provided but without an `errorCallbackURL` then they will be redirected to the callbackURL with an `error` query parameter.    },});

const data = await auth.api.magicLinkVerify({    query: {        token: "123456", // required, Verification token.        callbackURL: "/dashboard", // URL to redirect after magic link verification, if not provided will return the session.        newUserCallbackURL: "/welcome", // URL to redirect after new user signup.        errorCallbackURL: "/error", // URL to redirect if an error happens on verification. If only callbackURL is provided but without an `errorCallbackURL` then they will be redirected to the callbackURL with an `error` query parameter.    },    // Pass the current request headers so Better Auth can read and set cookies.    headers: await headers(),});

Configuration Options

sendMagicLink: The sendMagicLink function is called when a user requests a magic link. It takes an object with the following properties:

• email: The email address of the user.
• url: The URL to be sent to the user. This URL contains the token.
• token: The token if you want to send the token with custom URL.
• metadata: Additional request metadata passed from signIn.magicLink.

and a ctx context object as the second parameter.

expiresIn: specifies the time in seconds after which the magic link will expire. The default value is 300 seconds (5 minutes).

allowedAttempts (deprecated): Each verification call now consumes the token atomically on the first attempt, so retries always fail with ?error=INVALID_TOKEN regardless of this setting. The option is kept for source compatibility but ignored; multi-attempt redemption is no longer supported. Setting it to any value other than 1 emits a console.warn at startup (including 0, which previously rejected immediately and now has no effect).

disableSignUp: If set to true, the user will not be able to sign up using the magic link. The default value is false.

rateLimit: Rate limit for the /sign-in/magic-link and /magic-link/verify endpoints. The default value is { window: 60, max: 5 }. See Rate Limit for details.

generateToken: The generateToken function is called to generate a token which is used to uniquely identify the user. The default value is a random string. There is one parameter:

• email: The email address of the user.

storeToken: Controls how Better Auth transforms the Magic Link token before creating its verification identifier. The default value is "plain".

The storeToken option can be one of the following:

• "plain": The token is not transformed before Better Auth creates its verification identifier.
• "hashed": The token is hashed using the default hasher before the identifier is created.
• { type: "custom-hasher", hash: (token: string) => Promise<string> }: Your hasher transforms the token before the identifier is created.

Better Auth adds magic-link: to the transformed token before applying the global verification.storeIdentifier setting. The token value sent in the link and to sendMagicLink is unchanged. Custom storeToken hashers receive the original token; they do not need to add the prefix.

The storage backend itself is controlled by the global verification config. If you configure secondaryStorage, magic link verification records can be stored there instead of the database.

When upgrading to purpose-prefixed verification identifiers, request new Magic Links for any links issued before the upgrade. Previously issued links cannot be redeemed by the new version and fail with INVALID_TOKEN. Existing users and accounts do not need a data migration. Upgrade all servers that share verification storage together so they agree on which links can be redeemed.