Magic Link & Email OTP

Two ways to sign a user in without a password, both of which prove control of an inbox: a link they click, or a code they type. Neither stores a password, so neither has a password to leak or reset.

They are enabled through different mechanisms — the link is a strategy entry, the code is not. That asymmetry is the one thing to get right on this page.

Magic Link

A strategy entry. The user submits their email, receives a one-time link, and is signed in by following it.

auth:
  strategies:
    - type: magicLink
      expirationMinutes: 30

The default 15 minutes assumes the user is waiting on the mail. Stretch it when your audience checks email on a phone, later; shorten it when the link grants access to something sensitive, since a live link in an inbox is a live credential.

The message body is rendered from the magicLink email template when you supply one, with $url substituted for the link.

Enabling Email-OTP

Email-OTP delivers a numeric one-time code instead of a link — better on a device where following a link would break the flow, and easier to read aloud over a phone.

There is no type: emailOtp strategy entry. The flow activates when you define the emailOtp email template; its presence is what mounts the plugin.

auth:
  strategies:
    - type: emailAndPassword
  emailTemplates:
    emailOtp:
      subject: Your sign-in code
      text: 'Your verification code is $code. It expires shortly.'

$code is substituted with the generated one-time code. Note the strategy array above declares only emailAndPassword — email-OTP rides alongside whatever strategies you declared, it does not replace them.

Both Need SMTP

A passwordless flow that cannot send mail cannot sign anyone in. When SMTP is unset the app boots with email disabled and logs a warning — sign-in attempts then fail silently, with the user waiting on a message that was never sent.

Configure SMTP before shipping either flow, and prefer keeping emailAndPassword declared alongside them while you do: it gives you a working way in if mail delivery breaks. See Environment Variables for the SMTP settings.

Related Pages

• Strategies Overview — the strategies array and how to choose.
• Email Templates — the magicLink and emailOtp bodies and their variables.
• Email & Password — the credential strategy these sit beside.
• Environment Variables — SMTP configuration and BASE_URL.
• Sessions — the session a successful link or code issues.