Mailmus
Auth

MFA (two-factor authentication)

TOTP verification at sign-in, and enrollment (QR code and backup codes).

Mailmus Auth supports TOTP (Google Authenticator, 1Password, Authy, and others) — no SMS, which rules out the whole class of vulnerabilities tied to SIM swapping.

There are two distinct flows: enrollment (the user turns MFA on for their account) and verification (MFA is already on, and fires at every sign-in).

Verification — at every sign-in

Every first-sign-in method (signIn, verifyOtp, verifyMagicLink, resetPassword, OAuth) returns an MFA challenge instead of tokens when the user has MFA on:

const result = await auth.signIn({ email, password });

if (isMfaChallenge(result)) {
  // { mfaRequired: true, challengeToken: string }
  const { customer } = await auth.mfa.verify({ challengeToken: result.challengeToken, code: "123456" });
} else {
  console.log(result.customer);
}

code accepts a 6-digit TOTP code or a 10-character backup code (consumed and invalidated after use — each one works once).

With @mailmus/auth-react, <SignIn> handles this step for you: the component switches to a built-in verification form as soon as signIn() returns a challenge, with no extra code on your side.

Enrollment — turning MFA on

This is a three-step flow, done once while the user is already signed in (unrelated to the verification flow above):

// 1. Start enrollment — generates a TOTP secret and a QR code.
const { secret, otpauthUrl } = await auth.mfa.enroll();

// 2. Show the QR code (encode otpauthUrl, with the `qrcode` library for
//    instance) and/or the secret for manual entry, then collect the first
//    code generated by the user's authenticator app.

// 3. Confirm — MFA is only turned on at this step.
const { backupCodes } = await auth.mfa.confirm({ code: "123456" });
// backupCodes: string[10] — shown once; the user has to save them.

backupCodes is returned once, at confirmation — Mailmus stores them hashed only, so they cannot be asked for again later. Plan a UI that makes the user copy or download them before moving on.

Turning MFA off

await auth.mfa.disable({ code: "123456" }); // TOTP or backup code

With @mailmus/auth-react

<MfaEnroll> covers the whole enrollment flow (QR code, manual secret, confirmation, and the backup codes with a copy button):

<MfaEnroll onEnrolled={(backupCodes) => console.log(backupCodes)} />

<MfaDisable> covers turning it off:

<MfaDisable onDisabled={() => console.log("MFA turned off")} />

No equivalent component exists anywhere else in the Mailmus ecosystem (not on the hosted pages, not in the admin panel) — this is the only ready-made MFA enrollment UI.

Next

  • OAuth — MFA applies to Google, GitHub and Apple sign-ins too.
  • API Reference — the mfa/* endpoints.

On this page