> This page is for Agent Handler.

> 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

> How to set up MFA per user, enforce MFA org-wide, and reset a member's MFA as an admin.

MFA adds a second factor (a TOTP code from an authenticator app) to dashboard logins. By default it's optional per member. Most teams turn it on org-wide once they have a few people using the dashboard.

If your team uses [SSO](/merge-agent-handler/administer/sso), MFA is usually enforced at the IdP rather than at Agent Handler - your IdP already requires the second factor before SSO completes, so layering MFA at Agent Handler too is redundant.

## Setting up MFA on your account

Each member sets up their own. From [Settings → Profile](https://ah.merge.dev/settings/profile):

1. Click **Enable MFA**.
2. Scan the QR code with an authenticator app - 1Password, Google Authenticator, Authy, Microsoft Authenticator, anything that supports TOTP.
3. Enter the 6-digit code the app shows.
4. Save the recovery codes Agent Handler displays. These are the only way back in if you lose your authenticator. Store them somewhere durable - your password manager, not your laptop.

From the next login on, MFA is required for your account.

## Requiring MFA org-wide

Admins can require MFA for everyone in the org at [Settings → Organization → Security](https://ah.merge.dev/settings/organization). Once on:

* Existing members without MFA are forced to enroll on next login. The login flow won't proceed until they finish enrollment.
* New invitations include MFA enrollment as part of first login.
* Members who already had MFA aren't affected.

Turn this on once your team is small enough that a few minutes of friction per person is acceptable, or when your security review asks.

## Admin reset

If a member loses their authenticator and their recovery codes, an admin can reset their MFA. From [Settings → Members](https://ah.merge.dev/settings/organization), click the member, then **Reset MFA**. The member can re-enroll on their next login.

Reset is logged in the [Audit Trail](/merge-agent-handler/observe/audit-trail) - a record exists of who reset whose MFA and when.

## Common issues

* **Codes always rejected.** Check the device's clock. TOTP codes are time-based; a clock more than \~30 seconds off the server will produce codes that look right but fail.
* **No QR code shown.** Browser blocked the image, or the page errored. Refresh; if it still fails, contact support.
* **Lost recovery codes and authenticator.** Ask an admin in your org to reset MFA from the member dashboard. If you're the only admin, contact support - they'll verify you're the legitimate owner of the account before resetting.

## Next

See plans, usage, and how to upgrade in [Billing and usage](/merge-agent-handler/administer/billing).