POST/api/v1/mfa/factors创建一个 MFA 因素

Try it 面板需要启用 JavaScript。

创建处于待确认状态的 TOTP 因素，返回 otpauth URI 供验证器扫码；确认后生效。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	会话令牌认证，格式 `Bearer <sessionToken>`
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 会话令牌认证，格式 `Bearer <sessionToken>` */
  Authorization: string
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Authorization": "Bearer st_7c1f9e05b28d4a63",
  "Content-Type": "application/json"
}

Body

Name	Data Type	Required	Description
type	string	Yes	因素类型：totp

type RequestBody = {
  /** 因素类型：totp */
  type: string
}

{
  "type": "totp"
}

Response

Body

Name	Data Type	Required	Description
factorId	string	Yes	因素 ID
type	string	Yes	因素类型
status	string	Yes	固定为 pending
otpauthUrl	string	Yes	验证器扫码 / 录入的 otpauth URI
expiresAt	string	Yes	待确认状态过期时间，过期需重新创建

type ResponseBody = {
  /** 因素 ID */
  factorId: string
  /** 因素类型 */
  type: string
  /** 固定为 pending */
  status: string
  /** 验证器扫码 / 录入的 otpauth URI */
  otpauthUrl: string
  /** 待确认状态过期时间，过期需重新创建 */
  expiresAt: string
}

{
  "factorId": "01JD8SKH5N6P9W5XP9T4WDJ7U0C",
  "type": "totp",
  "status": "pending",
  "otpauthUrl": "otpauth://totp/Xeegam%20Passport:chenlin?secret=JBSWY3DPEHPK3PXP&issuer=Xeegam%20Passport",
  "expiresAt": "2026-10-14T08:50:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回待确认因素
409	状态冲突	已存在同类型因素

Response Code

响应使用统一信封 {id, code, messages, result}，其 code 字段：

code	Meaning	Notes
0	成功	返回待确认因素
2205	因素类型已存在	已绑定同类型的生效因素

Examples

POST /api/v1/mfa/factors
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "type": "totp"
}

{
  "id": "01JD8SKJK5N2M6M7",
  "code": 0,
  "messages": [],
  "result": {
    "factorId": "01JD8SKH5N6P9W5XP9T4WDJ7U0C",
    "type": "totp",
    "status": "pending",
    "otpauthUrl": "otpauth://totp/Xeegam%20Passport:chenlin?secret=JBSWY3DPEHPK3PXP&issuer=Xeegam%20Passport",
    "expiresAt": "2026-10-14T08:50:00Z"
  }
}