> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Multi-factor authentication

> Setting up an authenticator app, requiring MFA org-wide, resetting a member's device, and how MFA interacts with SSO.

Gateway asks for a 6-digit code from an authenticator app after the password. Each member enrolls their own device, and anyone with the **Manage users** permission can require MFA for the whole organization.

MFA is a password sign-in feature. If your organization signs in through an identity provider, the second factor belongs there, and turning on Gateway MFA does not add a step to the SSO flow.

## Set up your own device

Go to **Settings → Authentication** and choose **Set up**. Gateway shows a QR code with the same secret beside it as copyable text, so an authenticator that cannot scan can still be added by hand.

Enter the first code from the app and choose **Finish setup**. That code is what switches MFA on: until it is confirmed the device counts as unenrolled, so a bad scan cannot lock you out of your own account.

Once MFA is on, the card carries an **Enabled** badge and offers two more actions:

| Action                | What it does                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Change MFA device** | Runs setup again for a new authenticator. The new device is only in use once you confirm a code from it       |
| **Disable MFA**       | Removes the second factor from your account. Greyed out, with a tooltip, while your organization requires MFA |

## Require MFA across the organization

**Settings → Authentication** carries an **Organization settings** card with a toggle that enforces MFA for every member. The card is visible only to members who hold **Manage users**, which the [Admin and Security roles](/merge-gateway/security/roles-and-permissions) include.

Once the requirement is on:

* Members who already have an authenticator are asked for a code after their password
* Members who do not enroll on the sign-in screen itself, so nobody is locked out waiting for an admin
* **Disable MFA** is refused for everyone, in the dashboard and at the API

## See who is covered, and reset a lost device

**Settings → Organization** gives the member list an **MFA** column reading **Enabled** or **Not enabled**, which is the fastest way to see where the requirement bites before you turn it on.

When someone loses their phone, a member with **Manage users** picks **Reset MFA** from that member's row menu. The option appears only for members who currently have MFA on. Resetting clears their enrollment so the next sign-in enrolls a new device.

Gateway issues no recovery or backup codes, so an admin reset is the only way back in for someone who has lost their authenticator.

## Audit events

Every MFA action is recorded in the [audit trail](/merge-gateway/security/audit-trail) under the `MFA_` prefix: `ENABLED`, `DISABLED`, `DEVICE_CHANGED`, `ADMIN_RESET`, `VERIFICATION_FAILED`, `REQUIRED_ENABLED`, and `REQUIRED_DISABLED`.

`VERIFICATION_FAILED` is the one worth alerting on. A run of failures against one account is either a member whose device clock has drifted or someone working through stolen passwords.

Next: [Roles and permissions](/merge-gateway/security/roles-and-permissions)