Skip to content

Manager OTP Flow

Manager OTP Flow

This server uses TOTP for manager two-factor authentication with the following parameters:

  • Algorithm: SHA1
  • Digits: 6
  • Period: 30s
  • Compatible apps: Google Authenticator, Authy, and other standard TOTP apps

High-Level Rules

  • OTP is disabled when manager otp_secret is empty.
  • OTP is enabled when manager otp_secret is stored successfully.
  • QR code generation is performed on the client side using otp_url.
  • After OTP is enabled, AuthManager requires otp_code in addition to id and password.
  • online is runtime-only and is not related to OTP persistence.

1. Request setup data

Call GetManagerOTP.

Server returns: - secret - otp_url - algorithm - digits - period

2. Render QR code in UI

Use otp_url to draw the QR code in the interface.

3. Manager scans QR code

The manager scans the QR code with Google Authenticator.

4. Confirm setup

The manager enters the current code from the authenticator app. Call SetManagerOTP with: - secret - code

If valid, the server stores the secret and enables OTP.

5. Login with OTP

After activation, call AuthManager with: - id - password - otp_code

If OTP is enabled and otp_code is missing, login is rejected with OTP_REQUIRED.

Secret Rotation Flow

If OTP is already enabled and you want to replace the secret:

  1. Call GetManagerOTP to get a new secret and otp_url.
  2. Scan the new QR in the authenticator app.
  3. Call SetManagerOTP with:
  4. secret (new)
  5. code (from new secret)
  6. current_code (from current active secret)

This prevents silent takeover of an already protected manager account.

Verification Flow

Use CheckManagerOTP when you need to validate the current authenticator code without changing manager settings.

Reset Flow

To disable OTP:

  1. Ask the manager for the current authenticator code.
  2. Call ResetManagerOTP with code.
  3. If valid, the server clears the stored secret and disables OTP.

Login Behavior Summary

OTP disabled

AuthManager requires: - id - password

OTP enabled

AuthManager requires: - id - password - otp_code

Flowchart

flowchart TD
    A[Manager opens security settings] --> B[Call GetManagerOTP]
    B --> C[Server returns secret and otp_url]
    C --> D[UI renders QR code]
    D --> E[Manager scans QR in Google Authenticator]
    E --> F[Manager enters current code]
    F --> G[Call SetManagerOTP with secret and code]
    G -->|valid| H[Server stores otp_secret]
    G -->|invalid| I[Return INVALID_OTP_CODE]
    H --> J[OTP enabled]
    J --> K[Manager tries AuthManager]
    K --> L{otp_secret exists?}
    L -->|no| M[Password-only login]
    L -->|yes| N[Require otp_code]
    N --> O{otp_code valid?}
    O -->|yes| P[Login success]
    O -->|no| Q[Return INVALID_OTP_CODE]