Magic Link plugin for passwordless authentication
Better Auth includes a Magic Link plugin that provides passwordless email magic link authentication.
Better Auth · Plugins · all subjects
magic link plugin
18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Magic link plugin installation on server
Import the magicLink plugin from 'better-auth/plugins' and add it to the plugins array in betterAuth configuration. The plugin requires a sendMagicLink callback function that receives an object with email, token, url, and metadata properties, plus a ctx context object.
Magic link plugin installation on client
Import magicLinkClient from 'better-auth/client/plugins' and add it to the plugins array in createAuthClient configuration.
Sign in with magic link client method
Call the signIn.magicLink client method with the user's email address to request a magic link. This method is available after adding the magicLinkClient plugin to the auth client.
signIn.magicLink endpoint parameters
The POST /sign-in/magic-link endpoint accepts the following parameters: email (string, required) - email address to send the magic link; name (string, optional) - user display name used only if registering for the first time; callbackURL (string, optional) - URL to redirect after magic link verification; newUserCallbackURL (string, optional) - URL to redirect after new user signup; errorCallbackURL (string, optional) - URL to redirect if an error occurs during verification; metadata (Record<string, any>, optional) - additional metadata forwarded to the sendMagicLink callback.
Magic link verification endpoint
The GET /magic-link/verify endpoint manually verifies a magic link token. It accepts a token parameter (string, required) containing the verification token and an optional callbackURL parameter (string) to redirect after verification. If callbackURL is not provided, the endpoint returns the session.
Manually verify magic link without using endpoint
Use the verify function to handle magic link verification manually. This allows you to send the user a different URL and verify the token programmatically rather than through the /magic-link/verify endpoint.
Magic link sendMagicLink callback function
The sendMagicLink callback function is called when a user requests a magic link. It receives an object with the following properties: email (the email address of the user), url (the URL to be sent to the user containing the token), token (the token if you want to send it with a custom URL), and metadata (additional request metadata passed from signIn.magicLink). The function also receives a ctx context object as the second parameter.
Magic link expiresIn configuration
The expiresIn configuration option specifies the time in seconds after which the magic link will expire. The default value is 300 seconds (5 minutes).
Magic link allowedAttempts configuration deprecated
The allowedAttempts option is 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. Setting it to any value other than 1 emits a console.warn at startup.
Magic link disableSignUp configuration
The disableSignUp configuration option, when set to true, prevents users from signing up using the magic link. The default value is false.
Magic link generateToken configuration
The generateToken configuration function is called to generate a token which uniquely identifies the user. It takes one parameter: email (the email address of the user). The default value is a random cryptographically secure string. The returned string should be hard to guess as it is used to verify identity in a confidential way.
Magic link storeToken configuration
The storeToken configuration option controls how the magic link token is transformed before storage by Better Auth's verification layer. The default value is 'plain'. It can be one of: 'plain' (token stored in plain text), 'hashed' (token hashed using the default hasher), or { type: 'custom-hasher', hash: (token: string) => Promise<string> } (token hashed using a custom hasher).
Magic link auto signup behavior
If a user has not signed up, unless disableSignUp is set to true, the user will be signed up automatically when they sign in with a magic link.
Magic link verification with unconfirmed email
When a magic link verifies a pre-existing account whose email was never confirmed, any existing password on that account is removed and its sessions are revoked. The user is signed in through the link and can set a new password through password reset. Email ownership, proven by the link, becomes the source of truth for the account.
Magic link default redirect behavior
If no callbackURL is provided during magic link verification, the user will be redirected to the root URL.
Magic link error redirect behavior
If an error occurs during magic link verification and no errorCallbackURL is provided, the user will be redirected to the callbackURL with an error query parameter.
Magic link secondaryStorage verification requirement
When secondaryStorage backs verification (verification.storeInDatabase: false), the atomic single-use guarantee requires your secondary storage to expose getAndDelete (Redis GETDEL, KV getAndDelete). Better Auth does not fall back to separate get and delete operations for verification consumes. Multi-instance deployments using secondary-storage verification must configure a backend that implements getAndDelete.