Two-step verification

Two-step verification asks for a second proof after the first: a six-digit code from an authenticator app (1Password, Google Authenticator, Authy) or sent by email. Even if a password leaks, the account stays safe.

Multi-factor page — Users & auth → Multi-factor: strategies and who must use them.

A completed second step makes the session aal2 (the first step alone is aal1). Your access rules can require aal2 for sensitive actions, with the mfa shorthand.

In Studio

Users & auth → Security → Multi-factor.

Two-step verification

Setting	Meaning	Key
Allow two-step verification	Off hides enrolment and stops asking. People already enrolled keep their factors	`mfa_enabled`

Strategies

What people can use as a second step. They may enrol in more than one.

Setting	Meaning	Key
Authenticator app	A six-digit code from an app. Default on	`directory.mfa.totp`
Email code	A six-digit code sent to the account’s address. Convenient, and only as safe as the mailbox	`directory.mfa.email`
Backup codes	One-time codes shown once at enrolment, for when the phone is lost	`directory.mfa.backup_codes`
Backup codes per person	How many are issued. Default 10	`directory.mfa.backup_code_count`
Emailed code lifetime	Minutes. Default 10	`directory.mfa.email_code_minutes`

Who must use it

When required, a person without a second factor is walked through setting one up before they get a session.

Setting	Meaning	Key
Require two-step verification	Nobody (`off`), Administrators (`admins`: people with an admin or owner role, staff accounts, and owners or admins of an organization), or Everyone (`all`)	`directory.mfa.require`
Grace period	Days a new account may sign in without one. 0 asks at the first sign-in	`directory.mfa.grace_days`

People

An Enrolled / Not enrolled list of everyone. Reset removes a person’s second factors so they can sign in with a password alone and enrol again. Use it for someone who lost their phone and their backup codes, after confirming who they are.

Let a person enrol (authenticator app)

Start enrolment

The server makes a secret. Show it as a QR code and as text.

Confirm with a code

The person scans the QR code, then types the code their app shows. Pawabase checks it and switches two-step on.

Save backup codes

You receive one-time recovery codes once. Make the person save them.

const { otpauth_uri, secret, factor_id } = await pawabase.auth.mfa.enroll();
// Render otpauth_uri as a QR code with any QR library. Show `secret` for manual entry.

const { enabled, recovery_codes } = await pawabase.auth.mfa.verifyEnrollment(codeFromUser);
showOnce(recovery_codes);

enrollment = pb.auth.mfa.enroll()                 # {"factor_id", "secret", "otpauth_uri"}
result = pb.auth.mfa.verify_enrollment(code_from_user)
show_once(result["recovery_codes"])

To enrol email as the second step: pawabase.auth.mfa.enrollEmail() (enroll_email()), then confirm with the code that arrives. When an account has two-step verification, the first factor doesn’t finish. It returns mfa_required with a verify function:

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

if (result.status === "mfa_required") {
  result.factors;                                   // which factors the person has: e.g. ["totp", "email"]
  const session = await result.verify(codeFromUser); // an authenticator code or a backup code
}

result = pb.auth.sign_in_with_password(email=email, password=password)

if result.status == "mfa_required":
    session = result.verify(code_from_user)

Every first factor can return this: signInWithPassword, verifyEmailCode, verifyMagicLink, social return and passkeys. Handle it in one place. A wrong code is an AuthenticationError. Allow a few retries and offer “use a backup code”. To send the email code on demand, call pawabase.auth.mfa.challenge(result.mfaToken).

When enrolment is required

With Require two-step verification on, a person without a factor is walked through setting one up before they get a session. Use the step calls with the mfaToken from the sign-in result: startSetup({ mfaToken, method: "totp" | "email" }), then completeSetup({ mfaToken, code }), which returns recovery codes and a session.

When two-step is required, keep at least one strategy (authenticator app or email) switched on. With none, nobody can enrol and the requirement is ignored.

Check, turn off, and new backup codes

const status = await pawabase.auth.mfa.status();   // { enabled, aal, recovery_codes_remaining }

await pawabase.auth.mfa.disable(currentCode);
const { recovery_codes } = await pawabase.auth.mfa.regenerateRecoveryCodes(currentCode);

status = pb.auth.mfa.status()
pb.auth.mfa.disable(current_code)
codes = pb.auth.mfa.regenerate_recovery_codes(current_code)["recovery_codes"]

Disabling and regenerating both ask for a current code, so someone at a signed-in laptop can’t weaken the account.

Require it for sensitive actions

Use aal2 in an access rule to ask for a second step only where it matters: Choose All of: Users with role admin; Signed in with 2FA in the rule picker. If a person who is aal1 hits that rule, your app should send them through a step-up: prompt for a code with mfa.challenge and result.verify.

Auth events

user.mfa_enabled, user.mfa_disabled and user.mfa_reset are emitted for webhooks so you can notify people or alert your team.

Devices

Remember trusted devices.

Account recovery

Lost passwords and phones.

Getting started

Sign-in methods

Sign-up

Security

People

Developers

Two-step verification

In Studio

Two-step verification

Strategies

Who must use it

People

Let a person enrol (authenticator app)

When enrolment is required

Check, turn off, and new backup codes

Require it for sensitive actions

Auth events

Devices

Account recovery

​In Studio

​Two-step verification

​Strategies

​Who must use it

​People

​Let a person enrol (authenticator app)

​Sign in with a second step

​When enrolment is required

​Check, turn off, and new backup codes

​Require it for sensitive actions

​Auth events

Devices

Account recovery

In Studio

Two-step verification

Strategies

Who must use it

People

Let a person enrol (authenticator app)

Sign in with a second step

When enrolment is required

Check, turn off, and new backup codes

Require it for sensitive actions

Auth events