# Multi-Factor Authentication

MFA adds a time-based one-time code to signing in to the console.

> **Availability**
>
> MFA is available on **Cloud** and **Enterprise**.
>
> [See all editions →](https://docs.shellhub.io/about/editions)

## Set the recovery email first

The profile carries a **recovery email**, separate from the address you sign in with, and enabling MFA fails without it: the request is refused before the code you typed is even checked, so an empty recovery email looks like a wrong code unless you know to look. It is also half of the reset path — a reset sends one code to your sign-in address and another to the recovery one, and needs both — and it cannot be set from a locked-out account, which is the moment you would think of it.

## Enabling it

From **Account** › **Security**.

![The Multi-factor authentication setting in the account security section, with the control that enables it](https://docs.shellhub.io/img/shots/mfa.png)

Scan the QR code with an authenticator app:

![MFA QR Code waiting to be scanned](https://docs.shellhub.io/img/manual/mfa-setup.png)

Then confirm with a code from the app. From then on, sign-in asks for one:

![Login requiring 6-digit code](https://docs.shellhub.io/img/manual/mfa-login.png)

## Recovery codes

Setup produces a set of recovery codes. Save them somewhere that is not the phone holding the authenticator.

![Recovery codes screen](https://docs.shellhub.io/img/manual/mfa-recovery-codes.png)

Each is single use, and they are the way back in when the authenticator is lost. Lose both and recovery becomes a support matter.

![Recovery mail](https://docs.shellhub.io/img/manual/mfa-recovery-mail.png)

## What MFA covers

**Console sign-in.** That is its scope.

It does not gate SSH connections. An SSH connection is authorized by [access policies](https://docs.shellhub.io/manage/access-control/access-policies) against an [SSH identity](https://docs.shellhub.io/manage/access-control/ssh-identities), and MFA is not part of that path.

If you want a second, deliberate step in front of _connections_ rather than sign-in, that is `require_reauth` on a policy — see [Login Approvals](https://docs.shellhub.io/manage/access-control/login-approvals). The two are complementary: MFA protects the account, re-auth protects a connection.

## MFA and API keys

Every MFA endpoint refuses API keys. It is a human-only flow by construction — an API key holder has no browser and no authenticator, and allowing one to manipulate MFA state would undermine the point.

An automation that needs to reach devices should connect as an API key, which never has MFA because it never signs in. See [SSH Access](https://docs.shellhub.io/api/ssh-access).

## Account lockout

Wrong passwords and wrong MFA codes each lock an account out for a while. The third failure starts a lockout. Attempts sent during it are refused without being checked and do not count. A failure shortly after a lockout ends makes the next one four times longer. The first lasts `SHELLHUB_ACCOUNT_LOCKOUT_BASE`, so by default they run 1, 4, 16 and then 60 minutes, the cap set by `SHELLHUB_MAXIMUM_ACCOUNT_LOCKOUT`. After a lockout at the cap the count starts over. Setting `SHELLHUB_MAXIMUM_ACCOUNT_LOCKOUT` to 0 disables both lockouts.

Password lockout is keyed on the account and the client address, resolved through `SHELLHUB_PROXY_TRUSTED_IPS`. A self-hosted deployment behind a load balancer without that set correctly will lock out on the balancer’s address, so a lockout on an account applies to everyone signing in to it, wherever they are. See [Ports and Connectivity](https://docs.shellhub.io/about/ports-and-connectivity).

MFA lockout has its own counter, keyed on the account alone, whatever the address. Wrong codes from every sign-in add to it, and a correct password does not reset it. Someone who knows your password can therefore keep you out of the MFA step by sending wrong codes. A recovery code still signs you in during the MFA lockout, and clears it. Change your password once you are in, so nobody can start a new sign-in with the old one.

A sign-in already past the password step can still send wrong codes for 30 minutes after it started. The last of those can start one more lockout, so with the default cap the MFA lockout can last up to about 90 minutes after the password change.

## Where to go next

- [Single Sign-On (SAML)](https://docs.shellhub.io/manage/team/single-sign-on) — Delegating sign-in to your IdP.
- [Login Approvals](https://docs.shellhub.io/manage/access-control/login-approvals) — A second factor on connections.
