Setup 2FA

What it is used for

Lets the logged-in user enable TOTP-based two-factor authentication (2FA). After setup, login can require both password and a one-time code from an authenticator app (e.g. Google Authenticator).

User flow (what the user will do)

Page path: /[locale]/setup-2fa

1. Go to Setup 2FA From the account page, the user clicks Setup 2FA (shown only when 2FA is not yet enabled).

2. Generate secret The user clicks “Generate secret”. The app shows a TOTP secret (with copy button) and a QR code.

3. Add to authenticator The user opens their authenticator app, scans the QR code (or enters the secret manually), and adds the account.

4. Verify The user enters the current 6-digit code from the authenticator app and submits. If the code is correct, 2FA is enabled and they see a success message. If not, they see an error and can try again.

How it is implemented

• Route: /[locale]/setup-2fa.
• Entry point: Account page -> Setup 2FA button (shown only when !user?.totpEnabled).
• UI: src/containers/Setup2FA/index.tsx — two-step flow in two cards.
• API flow:
  1. Generate secret: User clicks “Generate secret”.
     • POST account/totp/generate/secret with body { recaptcha_token, csrf }.
     • Response includes the TOTP secret and a base64 QR image. UI shows the secret (with copy button) and the QR code.
  2. Verify: User adds the account in their authenticator app, then enters a current TOTP code.
     • POST account/totp/verify with body { recaptcha_token, code, csrf }.
     • On success: toast; backend enables 2FA for the account.
     • On failure: inline error (e.g. wrong code).
• API: CallAPI used directly in the container for both account/totp/generate/secret and account/totp/verify.
• reCAPTCHA: Used for both generate and verify (action setup_2fa); token sent in request body.
• CSRF: useCSRF() provides csrfJwt included in both requests.
• Translations: Setup2FA namespace.

Account flows index