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

# Multi-factor authentication

> Configure multi-factor authentication for Mage user accounts.

Only in Mage Pro.

Try our fully managed solution to access this advanced feature.

[Get started for free](https://cloud.mage.ai/sign-up?source=mfa)

## Overview

Multi-factor authentication (MFA) adds a second verification step when a user signs in.
After MFA is enabled for an account, Mage requires the user's password or SSO sign in
and then a 6-digit code from an authenticator app before issuing a session.

Mage supports time-based one-time passwords (TOTP), which work with authenticator apps
such as Google Authenticator, Microsoft Authenticator, Authy, and 1Password.

> [!NOTE]
>
> MFA is configured per user account. Each user must enable MFA from their own account settings.

## Pre-requisites

Before configuring MFA, make sure:

* User authentication is enabled. See [User authentication](https://docs.mage.ai/production/authentication/overview.md).
* Your Mage deployment has run the latest database migrations.
* The Mage server has the MFA dependencies installed from `requirements.txt`, including `pyotp`
  and `qrcode`.
* The user has access to an authenticator app that can scan QR codes.

## Enable MFA

**1. Open MFA settings**

Sign in to Mage and go to **Settings** → **Access & security** → **MFA**.

**2. Start setup**

Click **Set up MFA**.

**3. Install or open an authenticator app**

Open an authenticator app that supports TOTP codes. Mage supports apps such as:

* Google Authenticator
* Microsoft Authenticator
* Authy
* 1Password

**4. Scan the QR code**

Click **Next**, then scan the QR code with your authenticator app.

The QR code adds a new Mage entry to the authenticator app. The app will start showing
rotating 6-digit verification codes for that Mage account.

**5. Verify the code**

Enter the current 6-digit code from the authenticator app and click **Next**.

After the code is accepted, Mage shows a confirmation step.

**6. Complete setup**

Click **Complete Setup** to close the setup flow and return to the MFA settings page.

The status changes to **Active** after MFA is enabled for your account.

## Sign in with MFA

After MFA is enabled, signing in has two steps:

1. Enter your email or username and password, or complete your configured SSO sign in.
2. Enter the 6-digit code from your authenticator app on the MFA verification page.

If the MFA verification session expires, return to the sign in page and start again.

> [!WARNING]
>
> After too many invalid MFA codes, Mage temporarily locks MFA verification for that user.
> Wait 5 minutes, then sign in again and enter a new code from the authenticator app.

## Disable MFA

To disable MFA for your account:

**1. Open MFA settings**

Sign in to Mage and go to **Settings** → **Access & security** → **MFA**.

**2. Choose disable**

Click **Disable MFA**.

**3. Confirm with a current code**

Enter the current 6-digit code from your authenticator app and confirm.

Mage deactivates the active MFA devices for your account after the code is verified.

## Troubleshooting

| Issue | What to check |
| - | - |
| The MFA page does not appear | Confirm that your Mage version includes MFA and that user authentication is enabled. |
| QR code generation fails | Confirm that `pyotp` and `qrcode` are installed in the Mage server environment and restart the server after installing dependencies. |
| The verification code is rejected | Enter the newest 6-digit code from the authenticator app. If codes continue to fail, check that the device running the authenticator app has the correct time. |
| The verification page says the session expired | Sign in again to create a new MFA challenge session. |
| Disable MFA fails | Enter the current 6-digit authenticator code for the account that is signed in. |


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