Skip to content
Dashboard
Theme
Theme

Multi-factor authentication

Authenticator apps, passkeys and recovery codes, with environment and organization MFA policies.

View Markdown

  • 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.

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.

A wrong second factor returns user_factor_invalid; a flow that needs one returns mfa_required.