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

# Multi-factor authentication

> Require a second factor for everyone in your Gradient organization

# Multi-factor authentication

Multi-factor authentication (MFA) asks for a one-time code in addition to the usual sign-in. It
protects your candidate data if someone's email account or password is stolen.

In Gradient, MFA is a **setting for the whole organization**. You turn it on once and it applies
to every member. There is no per-person switch, and there is no account-wide default that
Gradient sets for you.

<Note>
  MFA settings live on **Settings, Identity and SSO**, which is an enterprise feature. If you do
  not see that page, contact your Gradient representative.
</Note>

## What Gradient supports: Authenticator apps only

Gradient uses **TOTP**, the six-digit code produced by an authenticator app such as Google
Authenticator, Microsoft Authenticator, 1Password, or Authy.

Gradient does **not** send codes by SMS. Text-message codes can be intercepted by SIM swapping,
and supporting them would mean holding a phone number for every member. An authenticator app
avoids both problems.

***

## Turning on MFA for your organization

You must be an **owner**. Identity settings, including MFA, are owner-only.

1. Go to **Settings, Identity and SSO**.
2. Scroll to **Authentication policy**, then to the **Authentication settings** block, and click
   **Edit**.
3. Under **Secondary authentication**, turn on **Require MFA for all users**.

<Frame caption="1 opens the block for editing, 2 is the switch that requires a second factor">
  <img src="https://mintcdn.com/gradient-fc5b2665/Ym5_OoSvO1_m1jVz/images/identity/authentication-settings-mfa.png?fit=max&auto=format&n=Ym5_OoSvO1_m1jVz&q=85&s=0e223dfadb022bf53d8d34a0879bbd7e" alt="The Authentication settings block with the Edit button and the Require MFA for all users toggle highlighted" width="1600" height="1038" data-path="images/identity/authentication-settings-mfa.png" />
</Frame>

The change applies at the next sign-in. Nobody is signed out, and sessions already open keep
working until they end normally.

<Warning>
  Enrollment happens at sign-in, so every member enrolls the next time they sign in. Tell your
  team before you turn this on, and pick a time when your administrators are available. Someone
  who cannot complete enrollment cannot reach the dashboard.
</Warning>

***

## What members see the first time

<Steps>
  <Step title="They sign in as usual">
    Email link, password, Google, or single sign-on, whichever your organization allows.
  </Step>

  <Step title="Gradient asks them to enroll">
    They scan a QR code with their authenticator app and enter the first six-digit code to
    confirm it works.
  </Step>

  <Step title="They save their recovery codes">
    Gradient shows a set of one-time recovery codes at enrollment. See below.
  </Step>

  <Step title="Every later sign-in asks for a code">
    They open their authenticator app and enter the current six digits.
  </Step>
</Steps>

***

## Recovery codes, and why they matter

Recovery codes are the way back in when someone loses their phone. Each code works once.

Tell your team to store them in a password manager, not in the notes app on the same phone that
holds the authenticator. A recovery code stored on the lost device is not a recovery code.

For your **break-glass owner**, the account you keep for emergencies, store the recovery codes in
your team password manager rather than with the person who owns the account. That is
what makes the account usable when the person is unavailable, which is exactly when you need it.

***

## MFA with single sign-on: Deciding who enforces it

If your organization uses [single sign-on](/docs/guides/sso), your identity provider probably enforces
MFA already. Adding Gradient MFA on top means members answer two prompts on the way in.

Most customers pick one of these:

| Choice                 | When it fits                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Identity provider only | Your provider enforces MFA for all applications, and your security team treats that as sufficient. This is the common choice. |
| Gradient MFA as well   | Your security policy requires the application to enforce its own second factor, independently of the identity provider.       |

Whichever you pick, keep MFA on your **break-glass owner**. That account signs in with an
email link rather than through your identity provider, so it does not inherit your provider's
MFA, and it is the one account that must not be easy to take over. See
[Plan for lockout](/docs/guides/sso#plan-for-lockout-before-you-enforce).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="A member lost their phone">
    They sign in with one of their recovery codes, then enroll their new device. If they have no
    recovery codes left, contact Gradient support: an administrator cannot reset another member's
    factor from the dashboard.
  </Accordion>

  <Accordion title="The code is rejected every time">
    Almost always a clock problem. The device running the authenticator app must have the correct
    time. Turn on automatic time in the phone settings and try again.
  </Accordion>

  <Accordion title="A member never saw the enrollment screen">
    They have a session that started before you turned MFA on. Ask them to sign out and sign in
    again.
  </Accordion>

  <Accordion title="We want MFA for some people only">
    That is not possible today. The policy applies to everyone in the organization. If you need
    per-person rules, enforce them in your identity provider instead.
  </Accordion>
</AccordionGroup>

***

## What MFA does not cover

* **Candidates.** They never sign in, so there is no second factor to ask for. Their assessment
  link is their credential. See [Authentication](/docs/guides/authentication).
* **API keys.** A key is a machine credential and is not subject to MFA. Rotate keys instead, and
  keep them out of shared documents. See [Managing API keys](/docs/guides/managing-api-keys).