magic link auth

passwordless login without writing your own token crypto. uses the verified better-auth module.

intent

take a builder from "let users sign in" to a working passwordless flow: request link, email it, verify, create session. the failure mode this prevents: a hand-rolled token scheme with predictable tokens, no expiry, or no single-use guarantee. use this when you need frictionless auth without password management overhead.

inputs

• database: postgres, sqlite, mysql, or any database better-auth supports. must be configured and accessible at runtime.
• email sender: a transactional email provider (resend, sendgrid, mailgun, or custom smtp). pair with the transactional-email skill for setup.
• BETTER_AUTH_SECRET: environment variable. a 32+ character random string used to sign tokens. generate with openssl rand -base64 32 or similar. store in .env or secrets manager, never commit.
• app url: the base url where verify links are routed (e.g., https://myapp.com). used to construct the magic link url sent in email.

procedure

step 1: configure the server

set up better-auth with the magic-link plugin and a sendEmail callback that connects to your email sender.

const { betterAuth } = require('better-auth');
const { magicLink } = require('better-auth/plugins');

const auth = betterAuth({
  database: db,
  secret: process.env.BETTER_AUTH_SECRET,
  plugins: [
    magicLink({
      sendMagicLink: async ({ email, url }) => {
        await sendEmail({
          to: email,
          subject: 'Your magic sign-in link',
          html: `<a href="${url}">Sign in to your account</a>. Link expires in 15 minutes.`,
        });
      },
    }),
  ],
});

input: database connection, sendEmail function, BETTER_AUTH_SECRET env var. output: auth instance with magic-link plugin ready to handle requests.

step 2: expose a request-link route

create an http endpoint (post /auth/magic-link/request) that accepts an email, validates it, and calls the plugin to generate and send a token.

app.post('/auth/magic-link/request', async (req, res) => {
  const { email } = req.body;
  await auth.magicLink.sendLink(email);
  res.json({ message: 'check your email' });
});

input: email address from client request body. output: http response (no sensitive data). the plugin sends the token via email. edge case: if email does not exist in the user table, decide whether to return the same response (prevent user enumeration) or tell the client to sign up first. edge case: if the email sender fails (network timeout, rate limit, bad credentials), catch and return a 5xx or retry.

step 3: expose a verify route

create an http endpoint (get /auth/magic-link/verify) that accepts a token (from the email link), validates it, marks it as used, and returns a session cookie.

app.get('/auth/magic-link/verify', async (req, res) => {
  const { token } = req.query;
  const result = await auth.magicLink.verifyLink(token);
  if (result.success) {
    res.setHeader('set-cookie', result.sessionCookie);
    res.json({ sessionId: result.sessionId });
  } else {
    res.status(401).json({ error: 'invalid or expired token' });
  }
});

input: token from query string (passed by email link). output: http response with session cookie and session id. the plugin guarantees single-use and expiry checks. edge case: if token is expired, the plugin returns error. if token was already used, the plugin returns error. if token format is invalid, the plugin returns error. edge case: if database write fails during "mark token as used", the request may timeout or return 5xx.

step 4: gate protected routes on session

on routes that require auth, read the session cookie server-side, validate it against the database, and reject requests without a valid session.

app.get('/dashboard', async (req, res) => {
  const session = await auth.getSession({ headers: req.headers });
  if (!session) {
    return res.status(401).json({ error: 'unauthorized' });
  }
  res.json({ user: session.user });
});

input: session cookie from request headers. output: user data if session is valid, 401 if not. edge case: if session is expired, the plugin returns null. if session was tampered with, signature validation fails. never trust a client claim of session id.

decision points

• session lifetime: set to 1 hour for high-security apps (admin, payments), 30 days for low-risk tools (community forum). configure in the betterAuth options.
• magic-link expiry: 15 minutes is standard. users who miss it resend. configure in the magicLink plugin options.
• email deliverability: a magic link in spam is a broken login. warm your sending domain, use spf/dkim/dmarc, monitor bounce rates. test with a real mailbox.
• rate limiting: add a rate limit on the request route (e.g., 5 requests per email per hour) or it becomes an email-bomb vector for attackers. use redis or in-memory store.
• user creation: on first magic-link verify, decide: auto-create the user account, or require a signup step first. if auto-create, you may need to ask for a name later.
• link reuse handling: the plugin marks tokens single-use. if a user clicks the same link twice in quick succession, the second click fails. communicate this clearly or offer a "resend" button on the verify page.

output contract

success state: a passwordless flow that issues single-use, time-bound tokens via email, verifies them, and creates a session on valid click. the verify endpoint returns a session cookie and session id. protected routes read the session server-side and reject unauthorized requests.

data format: tokens are opaque strings generated by better-auth. sessions are stored in the database with a sessionId, userId, expiresAt, and optional metadata. session cookies are httpOnly (recommended) and signed.

file/location: session data is persisted in the configured database. tokens are not persisted (single-use, verified on click, then discarded). logs should record request timestamps and email addresses for audit.

outcome signal

success: a user requests a link with their email, receives it within 30 seconds, clicks it, and is logged in. the same link fails on a second click with "invalid or expired token". an expired link (after 15 minutes) is rejected. a protected route returns 401 if no valid session cookie is present. if a token is reusable, expires after days instead of minutes, or a second click succeeds, the flow is broken. test end to end with a real email account and a clock set to verify expiry.