Magic Link

The magic-link method emails a single-use sign-in link. Clicking it hits the callback endpoint, which consumes the token and logs the user in — or, under the register-first policy, redirects to the register form with a verified-email token.

How It Works

sequenceDiagram
  actor U as User
  participant P as Login page
  participant A as Auth API
  participant S as Temp key store
  participant E as Email
  participant B as PostAuth pipeline
  U->>P: enter email
  P->>A: POST /login-magiclink
  A->>S: store MagicLinkPayload under token key
  A->>E: email callback link
  U->>A: GET /magiclink-callback?token=
  A->>S: consume token (single-use)
  alt existing account
    A->>B: authenticate → session + redirect
  else new email (register-first)
    A->>S: issue verified_key token
    A-->>U: redirect /register?verified_key=
    U->>A: submit names + verified_key
    A->>B: single INSERT → session
  end

1. User enters their email on the magic-link page (/auth/login-magiclink in multi-method mode)
2. POST sends a JSON payload — MagicLinkPayload{email, token, return, remember} — stored under the token key, and emails the callback link
3. GET /auth/magiclink-callback?token= consumes the token (single-use, constant-time compare, optional IP binding)
4. On success the post-auth pipeline resolves or creates the user, creates the session, and redirects (return payload or post-auth redirect)

Registration

Under CreateUserOnRegister a verified email with no account is redirected to {RegisterURL}?verified_key=<token> — the same read-only-email form AuthKnight and OTP use. Requires FuncUserExists (or the passwordless find-by-email fallback); missing config falls back to session-first with a Warn log.

Setup (multi-method)

mma, err := auth.NewMultiMethodAuth("/auth", []types.Method{
    auth.NewOTPMethod(a),
    auth.NewMagicLinkMethodFromAuth(a, nil, func(token string) string {
        return "/auth/magiclink-callback?token=" + token
    }),
})
mux.Handle("/auth/", http.StripPrefix("", mma.Handler()))

Routes

Notes

• The token is the store key itself — 128+ bits of entropy, single-use, TTL-bounded (utils.MagicLinkExpiresSeconds, 15 min)
• BindIP optionally binds the link to the requester's IP (off by default — proxies/mobile networks break it)
• The return parameter is filtered by IsSafeReturnPath before entering the emailed link — no open redirects
• Callback is AuthenticateViaUsername-optional: without it the endpoint still verifies + redirects, reusable for password-reset and other verify-by-email flows

A complete working example is available in examples/magiclink.