Docs
Open the console →
Guides

Multi-factor authentication

Enroll TOTP multi-factor authentication in Cloud Control, save your one-time recovery codes, sign in with a code, and disable MFA — all RFC 6238, built on node:crypto.

Cloud Control supports time-based one-time-password (TOTP) multi-factor authentication per RFC 6238, compatible with any standard authenticator app. MFA is per-user and, once enrolled, is required on every sign-in.

The security panel showing TOTP MFA enrollment

Enroll

  1. Start setup

    Call `POST /api/auth/mfa/setup` (or use the account UI). You receive a base32 secret and an otpauthUrl. Scan the URL as a QR code, or type the secret into your authenticator app.

  2. Confirm a code

    Enter the current 6-digit code and submit it to `POST /api/auth/mfa/enable`. A wrong or expired code is rejected without enabling MFA.

  3. Save your recovery codes

    On success you receive eight single-use recovery codes. They are shown exactly once and stored only as hashes — save them somewhere safe. Each lets you sign in once if you lose your authenticator.

Sign in with MFA

When MFA is enabled, `POST /api/auth/login` with a correct password returns { mfaRequired: true, mfaToken } instead of a session. Submit that mfaToken plus a current code (or a recovery code) to `POST /api/auth/mfa/verify` to receive your session. The challenge token is single-use.

Too many wrong codes locks you out

Five wrong codes lock MFA verification for 15 minutes with a 429, the same window as password lockout. This is audited as auth.mfa_locked. Use a recovery code if your device clock has drifted and codes keep failing.

Disable

Disable MFA with `POST /api/auth/mfa/disable`, supplying a current authenticator or recovery code to prove possession. Using a recovery code here is audited as auth.mfa_recovery_used.

MFA and ownership

Organization ownership can only be transferred to a member who has MFA enrolled — ownership is the maximum blast radius, so the bar is enrollment. See Transferring organization ownership.