Magic-link sign-in

Magic links are the cleanest auth UX a product can ship — one click and you are signed in. The implementation looks simple but has three subtle traps: link-preview prefetch (Outlook, Slack, iMessage will hit your URL before the user clicks), cross-device flows (request on a phone, click on a desktop), and the replay window that opens the moment the link leaves your sender. This page shows how to ship magic-link sign-in that handles all three correctly.

• 1A request endpoint that takes an email and always responds 200 — even for unknown addresses, otherwise you have enabled enumeration.
• 2256+ bits of entropy in the token, generated server-side with crypto.randomBytes.
• 3A persisted row { token_hash, email, created_at, expires_at, consumed_at?, source_session? } with a 10-15 minute TTL.
• 4The link uses POST, not GET, OR the GET handler simply renders a "confirm sign-in" page — never auto-consumes the token on first hit, because Outlook / Slack / iMessage will prefetch the URL.
• 5Single-use deletion (or atomic consumed_at update) on actual sign-in confirmation.
• 6Optional but recommended: bind the token to the originating browser session so cross-device clicks become explicit, not silent.

1. Request the magic link

   Always 200, always identical body. The created_at value lets you optionally pin tokens to the requesting browser (next recipe). Tokens are hashed before persisting so a DB read does not equal a takeover.

   import { Sndr } from '@rkiza/sndr';
   import { randomBytes, createHash } from 'node:crypto';
   
   const sndr = new Sndr(process.env.SNDR_API_KEY!);
   
   export async function requestMagicLink(
     email: string,
     /** The current session id of the browser that requested the link.
      *  Used downstream to detect cross-device clicks. */
     requestingSessionId: string,
   ) {
     const user = await db.user.findUnique({ where: { email } });
     if (user) {
       const raw = randomBytes(32).toString('base64url');
       const hashed = createHash('sha256').update(raw).digest('hex');
   
       await db.magicLink.create({
         data: {
           token_hash: hashed,
           user_id: user.id,
           requesting_session_id: requestingSessionId,
           expires_at: new Date(Date.now() + 15 * 60_000),
         },
       });
   
       const link = `https://yourdomain.com/auth/magic-link?token=${raw}`;
       await sndr.emails.send(
         {
           from: 'auth@yourdomain.com',
           to: email,
           subject: 'Sign in to yourdomain',
           text: `Click here to sign in:\n\n${link}\n\nLink expires in 15 minutes. If you did not request this, ignore this email.`,
           html: `<p><a href="${link}">Click here to sign in</a>.</p><p>Link expires in 15 minutes. If you did not request this, ignore this email.</p>`,
         },
         { idempotencyKey: `magic-${user.id}-${Math.floor(Date.now() / 900_000)}` },
       );
     }
   
     return { ok: true };
   }

2. Click-through: render confirmation, do not auto-consume

   The GET handler renders a 'Confirm sign-in' button. Email-client prefetchers (Outlook Safe Links, Slack, iMessage Smart Links) hit the GET — if you auto-consume the token there, the user clicks an invalid link. The confirmation button POSTs to actually consume.

   // GET handler — render the confirmation page, do nothing destructive.
   export async function showMagicLinkConfirmation(token: string) {
     if (!token) return { status: 404 };
     // Render <form method="POST" action="/auth/magic-link/confirm">
     //   <input type="hidden" name="token" value="..." />
     //   <button>Sign in as alex@example.com</button>
     // </form>
     // Do NOT mutate any state here.
     return { status: 200 };
   }
   
   // POST handler — atomic compare-and-consume.
   import { createHash } from 'node:crypto';
   
   export async function consumeMagicLink(
     token: string,
     /** Current browser session id at the moment of the POST. */
     consumingSessionId: string,
   ) {
     const hashed = createHash('sha256').update(token).digest('hex');
     const row = await db.magicLink.findUnique({ where: { token_hash: hashed } });
     if (!row || row.expires_at < new Date() || row.consumed_at) {
       throw new Error('invalid_or_expired_token');
     }
   
     // Cross-device detection: warn (or require a step-up) when the click
     // happens in a different browser than the request. Many products
     // accept it silently; security-sensitive products require either
     // matching session or an additional factor.
     const isSameBrowser = row.requesting_session_id === consumingSessionId;
   
     await db.$transaction([
       db.magicLink.update({
         where: { id: row.id },
         data: { consumed_at: new Date() },
       }),
       db.session.create({
         data: {
           user_id: row.user_id,
           // Mark cross-device sign-ins so audit log + UI can warn.
           cross_device: !isSameBrowser,
         },
       }),
     ]);
   
     return { user_id: row.user_id, cross_device: !isSameBrowser };
   }

FAQ

Related