# Multi-factor authentication

## Factors

- **Authenticator apps (TOTP):** enrolment shows a QR code drawn on the server, so no third party sees the secret.
- **Passkeys:** see [passkeys](/user-management/passkeys/).
- **Recovery codes:** one-time codes issued at enrolment. Each use is audited.

SMS codes are not offered.

## Policy

`mfa_policy` in `PUT /v1/user_management/settings` is `off`, `optional` or `required`. When MFA is required, a correct first factor leaves the session waiting for the second; no code or token is issued until it is done. Organizations on Business and above can override methods and MFA with `PUT /v1/organizations/{org}/user_management_settings`.

When an organization requires MFA, every way into it asks for the second factor first: signing in, the organization chooser and automatic switch, an app's `organization_id` request, reusing an existing session, OAuth consent and device approval. That includes sessions that started before the organization turned MFA on: such a session grants nothing in the organization until the user passes MFA. With `prompt=none` the answer is `interaction_required`. If the policy cannot be read, the request is refused rather than let through.

Adding a factor to an account that already has one needs a sign-in in the last 10 minutes that passed a second factor, as removing one does; see the [account page](/user-management/hosted-login/#account-page).

A wrong second factor returns [`user_factor_invalid`](/errors/user_factor_invalid/); a flow that needs one returns [`mfa_required`](/errors/mfa_required/).
