MFA is a capability of Archie Auth. If your project uses a different authentication provider, this page does not apply.
Add MFA to your frontend
Build the enrolment and sign-in screens with the React SDK, the JavaScript SDK, or plain GraphQL.
Archie Auth getting started
Enable Archie Auth first if you have not done it yet.
What your users experience
Your users go through two short moments.- Set up. They scan a QR code with an authenticator app, such as Google Authenticator, Microsoft Authenticator, 1Password, or Apple Passwords. They type the first code to prove it works. Archie then shows them ten recovery codes.
- Every sign-in after that. They type their email and password, then the six-digit code from their app.
TOTP is the only factor available today. SMS and email are not offered as second factors.
Turn on MFA
You turn MFA on per project and per environment. Try it in a non-production environment first.1
Check the prerequisites
Archie Auth must be enabled for the environment. See Getting started.Every user must also have a role. Users without a role can sign in, but their requests to manage factors fail with
INSUFFICIENT_PERMISSIONS. Configure a default role for self sign-up, as described in Give new users a role. For accounts that already exist, assign a role from the Users tab with Edit roles.2
Open the Archie Auth settings
In the console, go to Backend → App Services → Authentication Providers → Archie Auth, then open the Settings tab.
3
Choose a mode
In the Two-Factor Authentication card, open the Second factor list and choose Off, Optional, or Required. See Choose a mode to decide.
4
Set the grace period
If you chose Required, enter the number of days in Grace period (days). Leave it empty to keep the stored value, which is 14 days when none is stored.
5
Save
Click Save MFA policy. The change applies to the current environment only.
6
Update your frontend
Your sign-in screens must handle the two new responses that MFA adds. Follow Add MFA to your frontend.
If the card says that two-factor activation is not available in this environment yet, the environment is not ready for MFA. Try another environment or contact Archie support.
Choose a mode
The policy has three modes.
Choose Optional while you build and test your screens. Move to Required when your frontend is live and tested.
The grace period
Required does not lock anyone out immediately. When you switch to it, Archie records the moment and starts a grace period, which is 14 days by default. During the grace period, users who have no factor can still sign in while they enrol. Keep these rules in mind:- Leave the field empty and Archie keeps the stored value. It uses 14 days when none is stored.
- Production never accepts a grace period below 1 day.
- Switching back to Optional during the grace period cancels the deadline. Switching to Required again starts a fresh one.
- A grace period of zero days enforces MFA at once and closes the active sessions of every user without a factor. The console asks you to type the environment name to confirm.
Turn MFA off
Switching to Off takes effect at once. It never deletes anyone’s factors. If you turn MFA back on, the factors your users already enrolled start working again.The policy covers user sign-ins only. Project API keys are not affected by it.
See who has enrolled
In the Users tab, the MFA column shows one of three states for each user: Second factor active, No second factor, or Couldn’t load.What changes in your app
With MFA on, a correct password does not always return a session. Your app must handle two extra responses at sign-in.
Both responses carry a short-lived handle in the error body. For GraphQL, the handle is in
errors[0].extensions. It is never an HTTP header, and you never put it in Authorization. The handle expires after five minutes for mfaToken and ten minutes for enrollToken. Each mfaToken works once.
The frontend guide shows complete code for each step.
Do not rely on a
methods field in AUTH_MFA_REQUIRED. Backends can return it empty or leave it out. Offer the authenticator code field, and offer the recovery code field as a fallback.Recovery codes
Archie shows ten recovery codes when a user finishes enrolment. Each code works once. The codes are shown only that one time and cannot be read again, so your app must make users save them before moving on. A recovery code gets a user back into their account, but it does not give them a session by itself. When a user redeems a code, Archie asks them to enrol a new authenticator. That replaces the old factor, stops the old authenticator from working, and issues ten new recovery codes.userMfaFactors reports recoveryCodesRemaining. The recoveryCodesLowWarning field turns true at three or fewer codes. This is a good moment to prompt the user to regenerate. Regenerating gives ten new codes and makes every previous code stop working.
Manage factors
userMfaFactors lists the factors of the signed-in user. Each factor has an id, a type, and a status.
Sensitive actions, such as removing a factor or regenerating recovery codes, need a session that presented a second factor in the last five minutes. If the session is older, the call fails with
AUTH_MFA_REAUTH_REQUIRED. Your app then asks for a fresh code and retries. This is called step-up. The frontend guide shows how.
When a user loses access
Users lose access in three common ways.
Administrators clear factors and lift lockouts with the
adminResetMfa and adminUnlockMfaFactor GraphQL operations. Both need an admin actor. adminResetMfa can answer MFA_ADMIN_CONFIRMATION_REQUIRED until you send confirm: true. The console has no button for these actions. Under Required, a user whose factors were cleared enrols again at the next sign-in.
Error reference
Every refusal carries one of these codes inextensions.code. Handle errors by code, never by message text.
The frontend guide explains each code with the exact response and the fix.
Operation reference
GraphQL
All operations live underarchieIdentity.
REST
All paths start with/auth/mfa.
Browsers on your own domain can only reach the GraphQL operations. Use REST from your server.
Common questions
Does this protect my Archie console account?
Does this protect my Archie console account?
No. This policy applies to the users of the app you are building. It does not change how you sign in to Archie.
Can I require a second factor for some users only?
Can I require a second factor for some users only?
Not today. The policy applies to everyone in the environment.
What happens to users who are signed in when I switch the policy on?
What happens to users who are signed in when I switch the policy on?
The change takes effect at their next sign-in. Users who already had a dormant factor are asked for it straight away. Enrolling a factor revokes that user’s earlier sessions, which is why the enrolment response hands your app a new session.
Are API keys affected?
Are API keys affected?
No. Project API keys authenticate a machine, not a person, and the policy does not apply to them.
Can a user enrol more than one authenticator?
Can a user enrol more than one authenticator?
One active factor at a time. To move to a new device, the user enrols again, which replaces the old factor and issues new recovery codes.