Skip to main content

Magic Link Recipe

Magic links provide passwordless authentication via email. No password required — users click a link to log in.

Email verification bonus

The first magic-link login automatically counts as email verification. No separate verification step needed.

Bearer mode

For native/mobile clients, add X-Auth-Strategy: bearer to /auth/magic-link/verify to receive tokens in the response body instead of cookies.

Step 1: Configure MagicLinkStrategy​

import { MagicLinkStrategy } from '@nik2208/node-auth';

const magicLinkStrategy = new MagicLinkStrategy({
  sendMagicLink: async (email, token, userId) => {
    await mailer.send({
      to: email,
      subject: 'Your login link',
      html: `<a href="https://yourapp.com/verify?token=${token}">Click to log in</a>`,
    });
  },
});
Built-in HTTP mailer

If you configure AuthConfig.email.mailer, node-auth will send magic-link emails automatically using the built-in templates (English and Italian). See the Mailer guide.

Step 2: Mount the router​

app.use('/auth', auth.router({ magicLinkStrategy }));

Step 3: Implement IUserStore methods​

Magic link requires these store methods:

async updateMagicLinkToken(userId: string, token: string | null, expiry: Date | null): Promise<void>
async findByMagicLinkToken(token: string): Promise<BaseUser | null>

Step 4: Test the flow​

# Step 1: Request magic link
curl -X POST http://localhost:3000/auth/magic-link/send \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'

# Step 2: Verify (token from email)
curl -X POST http://localhost:3000/auth/magic-link/verify \
  -H 'Content-Type: application/json' \
  -d '{"token":"<token-from-email>"}'
# Cookie mode: { "success": true } + HttpOnly cookies
# Bearer mode: add -H 'X-Auth-Strategy: bearer' → { "success": true, "accessToken": "…", "refreshToken": "…" }

Endpoints​

MethodPathDescription
POST/auth/magic-link/sendGenerate token + send magic-link email
POST/auth/magic-link/verifyVerify token → issue session tokens