Setup OTP

POST/web/v1/system/security/mfa/otp/setup JWT

Initializes TOTP (Time-based One-Time Password) setup by generating a new secret key and returning a QR code URI for the user's authenticator app. The secret is cached server-side for subsequent verification and is only returned once in this response.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token
X-SC-Session-Id		Secure channel session ID

Request Parameters

No request parameters required.

Request Example

No request body required.

Success Response

Success 200

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeUri": "otpauth://totp/SlaunchX:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=SlaunchX",
    "issuer": "SlaunchX",
    "accountName": "admin@example.com"
  }
}

Field	Type	Description
secret	string	TOTP secret key (Base32-encoded) for manual entry
qrCodeUri	string	otpauth:// URI for QR code scanning
issuer	string	Issuer name displayed in the authenticator app (always "SlaunchX")
accountName	string	Account identifier displayed in the authenticator app (user's email)

Error Responses

Unauthorized 401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Notes

• The secret and qrCodeUri are only returned once. After verification, the secret is encrypted and stored; it cannot be retrieved again.
• Rate limited to 5 requests per 300-second window.
• After calling this endpoint, use Verify OTP with a code from the authenticator app to confirm setup.
• The issuer is always "SlaunchX" and accountName is the user's email address.