Two-factor sign-in for your app's users

Your project's authentication supports two-factor sign-in with an authenticator app. Your app builds the screens, and the project does the checking. Once a user turns it on, a correct password alone is no longer enough.

How it works for a user

1. Enrol: the signed-in user asks to turn it on. Your app calls enrollMfa() and receives a secret and a provisioning_uri. Show the URI as a QR code so the user can scan it with an authenticator app.
2. Confirm: the user enters the current 6-digit code. Your app calls confirmMfa({ code }). The response contains backup codes, shown once. Ask the user to keep them somewhere safe.
3. Sign in: from now on, signIn returns mfa_required: true and a challenge_token instead of a session. Your app asks for a code and calls verifyMfa({ challengeToken, code }) to receive the session.
4. Turn off: disableMfa({ code }).

const login = await pgb.auth.signIn({ email, password });
if (login.mfa_required) {
  await pgb.auth.verifyMfa({ challengeToken: login.challenge_token!, code: "123456" });
}

The challenge is short-lived (five minutes). The same calls exist in the Python, Go and Rust SDKs (verify_mfa, VerifyMFA).

Test it in the Console

Open Authentication > Auth Playground and choose the Two-factor tab. You can check a test account's status, start enrolment, confirm with a current code, and verify a sign-in challenge. The Playground uses real accounts, so use a test user.

When a user loses their device

Backup codes are the first answer: each works once. If the user has none left, open the user in Authentication, choose Manage, then Remove two-factor and confirm. They can sign in with a password again and enrol a new device.

The Manage panel shows Two-factor on or Two-factor off next to each user, so you can see who has it enabled.

Good to know

• The Console does not force two-factor for your users. You decide whether your app offers it or requires it.
• Two-factor protects password sign-ins. Always keep your own Console account protected too.
• Removing someone's two-factor is recorded in their sign-in events.