Multi-factor authentication
Authenticator apps, passkeys and recovery codes, with environment and organization MFA policies.
Factors
Section titled “Factors”- Authenticator apps (TOTP): enrolment shows a QR code drawn on the server, so no third party sees the secret.
- Passkeys: see passkeys.
- Recovery codes: one-time codes issued at enrolment. Each use is audited.
SMS codes are not offered.
Policy
Section titled “Policy”mfa_policy in PUT / 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 /.
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.
A wrong second factor returns user_factor_invalid; a flow that needs one returns mfa_required.