Two-Factor Authentication (TOTP) API

The TOTP API binds time-based one-time password (TOTP) two-factor authentication to the signed-in account: generate the secret and QR code, verify and enable, disable, regenerate backup codes, and read status. Every operation acts on the caller's own account. Base path: /api/v1/totp.

Endpoints

Typical flow

1. POST /totp/setup: get the secret and QR code and scan them with an authenticator app; totp_enabled is still false.
2. POST /totp/enable: submit the current 6-digit code from the app to enable 2FA.
3. Later logins: POST /api/v1/login returns requires_totp plus a temp_token; call POST /api/v1/login/verify-totp to obtain the full token.

1. Generate binding information

POST /api/v1/totp/setup

Generates the secret, QR code, and backup codes for this binding. It does not enable 2FA — you must call enable and verify a code first.

No request body.

200 OK:

{
  "code": 0,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "backup_codes": [
      "1234-5678",
      "8765-4321",
      "2468-1357"
    ]
  },
  "msg": "success"
}

Errors:

2. Enable TOTP

POST /api/v1/totp/enable

Request body

200 OK:

{
  "code": 0,
  "data": null,
  "msg": "Two-factor authentication enabled successfully"
}

On success totp_enabled_at is recorded.

Errors:

3. Disable TOTP

POST /api/v1/totp/disable

Requires the account password plus a valid TOTP code or a backup code.

Request body

Disabling clears totp_enabled, totp_secret, totp_enabled_at, and the backup-code hashes.

200 OK:

{
  "code": 0,
  "data": null,
  "msg": "Two-factor authentication disabled successfully"
}

Errors:

4. Regenerate backup codes

POST /api/v1/totp/regenerate-backup-codes

Request body

200 OK:

{
  "code": 0,
  "data": {
    "codes": [
      "1234-5678",
      "8765-4321",
      "2468-1357"
    ]
  },
  "msg": "Backup codes regenerated successfully"
}

All previous backup codes are invalidated immediately, and 10 new XXXX-XXXX codes are generated.

Errors:

5. Get status

GET /api/v1/totp/status

200 OK:

{
  "code": 0,
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-26T10:15:00+00:00",
    "remaining_backup_codes": 10
  },
  "msg": "success"
}

6. Login-time verification (/api/v1/login/verify-totp)

When 2FA is required the login endpoint does not return a full token; it returns:

{
  "code": 0,
  "data": {
    "requires_totp": true,
    "temp_token": "<short-lived JWT for the next step>"
  },
  "msg": "..."
}

Then exchange the temp_token and a code for the full token:

POST /api/v1/login/verify-totp
Content-Type: application/x-www-form-urlencoded

temp_token=<temp_token>&code=123456&is_backup_code=false

Success returns the full Token object; failures return 400 + 5312 (totp_rate_limited, temporary lock after too many failures), 5311 (totp_invalid), 5313 (totp_not_enabled), or 2002 (totp_setup_expired, expired temporary token). Full fields and examples are in the Authentication API.

Error handling

Related

• Authentication API — login, the requires_totp / temp_token flow, and verify-totp
• Users API — account security operations
• Error Handling — recover by HTTP status and business error code