> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-factor authentication

> Turn on a second sign-in step for the users of your app. Learn what MFA is, how to enable it in the console, how the Off, Optional, and Required modes work, and how users recover their accounts.

Multi-factor authentication (MFA) adds a second step to sign-in. After users type their password, they also type a six-digit code from an app on their phone.

MFA protects **the users of your app**, meaning the accounts that Archie Auth manages. It does not change how you sign in to the Archie console.

> [!NOTE]
>
> MFA is a capability of Archie Auth. If your project uses a different authentication provider, this page does not apply.

> [card] [Add MFA to your frontend](https://archie.com/docs/backend/app-services/authentication-providers/archie-auth/multi-factor-authentication-frontend.md)
>
> Build the enrolment and sign-in screens with the React SDK, the JavaScript SDK, or plain GraphQL.

> [card] [Archie Auth getting started](https://archie.com/docs/backend/app-services/authentication-providers/archie-auth/getting-started.md)
>
> Enable Archie Auth first if you have not done it yet.

## What your users experience

Your users go through two short moments.

1. **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.
2. **Every sign-in after that.** They type their email and password, then the six-digit code from their app.

| | |
| - | - |
| Factor | Time-based one-time password (TOTP). Six digits, refreshed every 30 seconds. |
| Apps | Any standard authenticator app. |
| Backup | Ten single-use recovery codes, shown once at set up. |

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](https://archie.com/docs/backend/app-services/authentication-providers/archie-auth/getting-started.md).

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](https://archie.com/docs/backend/app-services/authentication-providers/archie-auth/multi-factor-authentication-frontend.md#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](#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](https://archie.com/docs/backend/app-services/authentication-providers/archie-auth/multi-factor-authentication-frontend.md).

> [!NOTE]
>
> 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.

| Mode | What happens |
| - | - |
| **Off** | Nothing changes. No user is asked for a second factor, and nobody can enrol one. |
| **Optional** | Users may enrol from your app. Users who enrol type their code at every sign-in. Users who do not enrol sign in as before. |
| **Required** | Every user must enrol. Users without a factor are sent through enrolment when they sign in. |

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.

> [!WARNING]
>
> Nothing tells your users about the deadline automatically. Announce it yourself before the grace period ends. Otherwise, users without a factor are stopped at sign-in on the day it expires.

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.

> [!NOTE]
>
> 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.

| Situation | Code | What your app does |
| - | - | - |
| The user has a factor. | `AUTH_MFA_REQUIRED` | Ask for the six-digit code, then send it with the `mfaToken`. |
| The user has no factor and the policy requires one. | `AUTH_MFA_ENROLLMENT_REQUIRED` | Run the enrolment screens with the `enrollToken`. |

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](https://archie.com/docs/backend/app-services/authentication-providers/archie-auth/multi-factor-authentication-frontend.md) shows complete code for each step.

> [!NOTE]
>
> 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`.

| Status | Meaning |
| - | - |
| `active` | Working normally. |
| `orphaned` | The factor outlived the project's encryption key and can no longer be verified. The user should remove it and enrol again. |
| `frozen` | The account is held after a suspicious change. Only an administrator can resolve it. |

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.

| Situation | What to do |
| - | - |
| The user lost their phone but still has recovery codes. | The user signs in, picks the recovery code option, and enrols a new authenticator. |
| The user mistyped the code too many times. | The factor locks and the error `AUTH_MFA_LOCKED` carries `lockedUntil`. Show that time in your UI. Each further failure extends the wait. |
| The user lost the phone and the recovery codes. | A project administrator must clear the factors so the user can enrol again. |

> [!WARNING]
>
> Verify who you are talking to before you reset or unlock anyone. Both actions are the recovery path an attacker would ask you to take for them. Resetting a user also signs them out everywhere.

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 in `extensions.code`. Handle errors by code, never by message text.

| Code | What to do |
| - | - |
| `AUTH_MFA_REQUIRED` | Ask for the code and send it with the `mfaToken`. |
| `AUTH_MFA_ENROLLMENT_REQUIRED` | Send the user through enrolment with the `enrollToken`. |
| `AUTH_MFA_INVALID_CODE` | Wrong code. The handle is still valid, so let the user retry. |
| `AUTH_MFA_TOKEN_EXPIRED` | The handle expired or was already used. Start again from sign-in. |
| `AUTH_MFA_LOCKED` | Too many failures. Show the time in `lockedUntil`. |
| `AUTH_MFA_REAUTH_REQUIRED` | The action needs a fresher second factor. Run a step-up. |
| `AUTH_MFA_METHOD_NOT_ALLOWED` | The session or method is not allowed to do this. |
| `AUTH_MFA_FACTOR_NOT_FOUND` | No such factor for this user. |
| `AUTH_MFA_NOT_ENABLED` | The policy is off for this project and environment. |
| `AUTH_MFA_UNAVAILABLE` | The service could not answer. Block the sign-in and retry later. |

The frontend guide explains each code with the exact response and the fix.

## Operation reference

### GraphQL

All operations live under `archieIdentity`.

| Operation | Purpose |
| - | - |
| `userMfaPolicy` | Query. The mode, the permitted `methods`, and `enforceFrom`. |
| `userMfaFactors` | Query. The caller's factors and how many recovery codes remain. |
| `userMfaEnroll` | Mutation. Start an enrolment. Returns the secret once. |
| `userMfaEnrollVerify` | Mutation. Activate the factor. Returns the recovery codes and a new session. |
| `userMfaVerify` | Mutation. Redeem an `mfaToken`, or step up the current session when you omit it. |
| `userMfaRemoveFactor` | Mutation. Remove a factor. Needs a stepped-up session. Refused for the last factor when the project requires MFA. |
| `userMfaRegenerateRecoveryCodes` | Mutation. Ten new codes. The old ones stop working. |
| `userReauthenticate` | Mutation. Confirm the current password. Only for the first enrolment of a user who has no factor. Users with a factor use step-up. |
| `adminResetMfa` | Mutation. Administrator only. Clear a user's factors. |
| `adminUnlockMfaFactor` | Mutation. Administrator only. Lift a lockout. |

### REST

All paths start with `/auth/mfa`.

| Method and path | Purpose |
| - | - |
| `GET /policy` | The policy for this project and environment. |
| `GET /factors` | The caller's factors. |
| `POST /enroll` | Start an enrolment. |
| `POST /enroll/verify` | Activate the factor. |
| `POST /enroll/email/send` | Send a verification code to the user's address. |
| `POST /enroll/email/verify` | Confirm that code. |
| `POST /verify` | Redeem a handle, or step up the session. |
| `DELETE /factors/{id}` | Remove a factor. |
| `POST /recovery-codes/regenerate` | Ten new recovery codes. |

Browsers on your own domain can only reach the GraphQL operations. Use REST from your server.

## Common questions

> [accordion] 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.

> [accordion] Can I require a second factor for some users only?
>
> Not today. The policy applies to everyone in the environment.

> [accordion] 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.

> [accordion] Are API keys affected?
>
> No. Project API keys authenticate a machine, not a person, and the policy does not apply to them.

> [accordion] 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.

> [accordion] What if the second factor service is unavailable?
>
> Sign-in is blocked instead of letting users through without the factor. You can always set the policy back to **Off**, which never depends on that service being healthy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.