Multi-factor authentication

During sign in

After any primary sign in, Auth UI calls account.get(). If Appwrite answers user_more_factors_required, Auth UI lists the factors the account can use and shows a chooser:

• Authenticator app (TOTP)
• Email code, available when the account's email is verified
• SMS code, available when the account's phone is verified
• Recovery code

Choosing a factor creates a challenge with createMFAChallenge(). For email and SMS this sends the code. The user enters the code and Auth UI completes the challenge with updateMFAChallenge(). Cancelling ends the partial session so the user can start over.

The same detection runs on every page load, so a user who refreshes in the middle of a challenge lands back on the chooser.

Enrolling

The Security tab of the account screen has a Two-factor authentication card:

1. Add authenticator calls createMFAAuthenticator("totp"). Auth UI renders the returned otpauth:// URI as a QR code using your own Appwrite endpoint's Avatars service, and prints the secret for manual entry.
2. The user scans it and types the six-digit code. updateMFAAuthenticator() verifies it.
3. Flip the Two-factor authentication switch to enforce MFA on the account with updateMFA(true).

Appwrite only requires a second factor when the account both has MFA enabled and has at least one usable factor. Auth UI still warns if you enable the switch with no authenticator and no verified email or phone, because the setting alone does not protect the account until a factor exists.

Recovery codes

Generate recovery codes creates a set of one-time codes and shows them with a copy button. Each code signs in once. On Appwrite 2.x the full list can be read only once after generation; later attempts need a fresh second factor (or regenerate). Regenerate replaces the whole set.

Step-up verification

Reading or regenerating recovery codes and removing an authenticator are protected: Appwrite requires a factor verified within the last 30 minutes and otherwise answers user_challenge_required. Verifying a newly enrolled authenticator does not count as that recent challenge on the server (unlike preview mode), so opening recovery codes right after enrolment often triggers step-up. Auth UI catches user_challenge_required, shows an inline challenge card, and retries the original action once the challenge succeeds.

Disabling MFA in the UI

Set mfa: false in the configuration to hide the MFA and recovery code cards. Challenges during sign in still appear, because they are enforced by the server for accounts that already have MFA on.