2FA 验证码.

所有请求都需要在 Authorization 请求头中携带 API 密钥。TOTP 密钥只通过 POST 请求体传递，不接受查询参数，也不支持 GET。

curl 示例

curl -X POST https://nexus.koopk.com/api/totp \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret":"JBSWY3DPEHPK3PXP"}'

成功响应

{
  "ok": true,
  "code": "287082",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30,
  "expires_in": 17,
  "expires_at": "2026-10-23T13:30:00.000Z",
  "generated_at": "2026-10-23T13:29:43.000Z"
}

字段	必填	说明
secret	二选一	Base32 密钥，或完整的 otpauth://totp/... 链接。
id	二选一	SQLite 账户库中的条目名。适合固定账号，避免在飞书表格中保存明文种子。
algorithm	否	SHA1（默认）、SHA256 或 SHA512。
digits	否	验证码位数，支持 6 或 8，默认 6。
period	否	有效期，5–300 秒，默认 30 秒。

参数优先级：请求中的 algorithm、digits、 period 会覆盖 otpauth 链接或 SQLite 账户中的同名设置； 如果未显式传入，则使用链接/账户中的值，最后回退到默认值。

错误格式：HTTP 状态码区分错误类型， error.code 提供稳定的机器可读标识，例如 unauthorized、invalid_secret。 响应中不会回显密钥。

保存账户到 SQLite（PUT）

curl -X PUT https://nexus.koopk.com/api/totp/accounts/feishu \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret":"JBSWY3DPEHPK3PXP","label":"飞书主账号"}'

SQLite 账户库：PUT 到 /api/totp/accounts/<id> 新增或更新账户；GET 同路径读取元数据，GET /api/totp/accounts 列出全部账户； DELETE 删除。接口不会返回 secret。之后请求验证码时传 {"id":"feishu"} 即可。

使用多维表格自动化中的「发送 HTTP 请求」动作。飞书支持自定义请求头和 raw JSON 请求体，可以直接调用此接口，并把返回值写回记录。

1. 01

   创建自动化流程

   在多维表格中新建自动化，设置触发条件（例如「当记录满足条件时」或 「点击按钮时」），然后添加「发送 HTTP 请求」动作。

2. 02

   填写请求

   请求方法选择 POST，URL 填 https://nexus.koopk.com/api/totp， 请求体类型选择 raw JSON。

   添加两个请求头：Authorization 的值为 Bearer YOUR_API_KEY； Content-Type 的值为 application/json。

   请求体

   {"secret":"JBSWY3DPEHPK3PXP"}

   把示例密钥替换成多维表格中的字段引用（点击输入框旁的「+ 引用值」）， 或先通过账户 API 保存密钥，再使用 {"id":"feishu"}。

3. 03

   解析返回值

   响应格式选择 JSON，返回值路径填写 code，写入字段请使用「单行文本」。 验证码可能以 0 开头，写入数字字段会丢失前导零。

   如需展示剩余时间，可再取 expires_in （整数秒）。

更稳妥的做法：先用 PUT /api/totp/accounts/feishu 把固定密钥保存到 SQLite 账户库，请求时只传 {"id":"feishu"}。这样多维表格中不会出现 明文 TOTP 种子；自动化配置即使被查看，也只泄露条目名。SQLite 数据库每天 备份到私有 COS 桶。

关于 API 密钥：它会被保存在自动化流程配置中， 所有能编辑该流程的人都可查看。请使用一把专用密钥并定期轮换； 不要与个人密码复用。