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.

---

Magic Link flow

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 AuthConfig

Magic links are enabled by providing a sendMagicLink callback (or a mailer configuration) in your AuthConfig:

const config: AuthConfig = {
  // ... secrets
  email: {
    // Option A: Use a custom callback
    sendMagicLink: async (email, token, link, lang) => {
      await mailer.send({
        to: email,
        subject: 'Your login link',
        html: `<a href="${link}">Click to log in</a>`,
      });
    },
    // Option B: Use the built-in HTTP mailer (see Mailer guide)
    // mailer: { endpoint: '...', apiKey: '...' }
  }
};

---

Step 2: Mount the router

The magic-link endpoints are active as long as the email configuration is present. No additional strategy needs to be passed to the router:

Express

app.use('/auth', auth.router());

NestJS

this.router = auth.router();

---

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

Method	Path	Description
POST	/auth/magic-link/send	Generate token + send magic-link email
POST	/auth/magic-link/verify	Verify token → issue session tokens