适用场景
2FA 动态验证码（TOTP）是双因子认证的核心技术，广泛应用于登录验证、交易确认、敏感操作授权等场景。该 API 基于 RFC 6238 标准，兼容 Google Authenticator 等主流身份验证器，支持生成、校验和批量三种操作模式。在工程集成中，开发者需要重点关注接口的调用频率限制和额度边界，以确保生产环境的稳定性和合规性。
接口能力边界
核心指标
- 请求方法：POST
- 端点：
https://v1.apizero.cn/api/2fa - 最大 QPS：20 次/秒（基于单个 IP 或单一 API Key）
- 额度差异：匿名调用（不带 Authorization 头）与携带 API Key 的调用，各自拥有独立的每日/每小时额度上限，具体数值以平台文档为准。
- 操作模式：
generate：生成当前周期的动态码verify：校验用户输入的验证码batch：返回上一个周期、当前周期和下一个周期的验证码（共三组），适合客户端容错场景
参数边界
| 参数 | 类型 | 必填 | 说明 | 约束范围 |
|---|---|---|---|---|
secret | string | 是 | Base32 编码的 TOTP 密钥，自动忽略空格与连字符，不区分大小写 | 长度至少 16 字符（128 位） |
action | string | 否 | 操作类型，默认行为取决于是否同时提供code。若只传secret则视为generate；若同时传secret和code则视为verify | generate/verify/batch |
code | string | 条件 | 当action=verify或未显式指定action但提供了code时必填 | 4~8 位数字 |
period | number | 否 | 验证码有效期（秒） | 10~120，默认 30 |
digits | number | 否 | 验证码位数 | 4~8，默认 6 |
超过参数范围会返回1001参数错误。
鉴权与请求头
API 提供两种鉴权路径，直接影响调用额度：
- 匿名调用：不添加
Authorization头，适用于开发测试或低频场景。 - API Key 调用：添加
Authorization: Bearer <你的 API Key>，额度更高，适合生产环境。
无论哪种方式，都必须设置Content-Type: application/json。
curl 接入示例
生成当前验证码（匿名）
curl -sS -X POST \ -H "Content-Type: application/json" \ -d '{"secret": "JBSWY3DPEHPK3PXP", "action": "generate"}' \ "https://v1.apizero.cn/api/2fa"校验验证码（使用 API Key）
curl -sS -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "secret": "JBSWY3DPEHPK3PXP", "code": "123456", "action": "verify" }' \ "https://v1.apizero.cn/api/2fa"批量获取三个周期（自定义参数）
curl -sS -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "secret": "JBSWY3DPEHPK3PXP", "action": "batch", "period": 60, "digits": 8 }' \ "https://v1.apizero.cn/api/2fa"返回值解读
成功响应示例（generate模式）：
{ "code": 0, "msg": "成功", "request_id": "abc123", "data": { "totp_code": "123456", "digits": 6, "period": 30, "remaining_seconds": 17, "next_refresh": "2026-06-30 12:00:30", "timestamp": 1782000000 } }字段含义
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务码，0 表示成功，非 0 表示错误 |
msg | string | 结果描述 |
request_id | string | 请求唯一标识，用于日志追踪 |
data.totp_code | string | 当前周期的验证码（generate/batch模式返回；verify模式成功时不返回此字段） |
data.digits | int | 实际使用的验证码位数 |
data.period | int | 实际使用的有效期（秒） |
data.remaining_seconds | int | 当前周期剩余秒数 |
data.next_refresh | string | 下一次刷新时间的 ISO 格式 |
data.timestamp | int | 服务端当前 Unix 时间戳（秒） |
verify模式下，若校验成功，data中不包含totp_code，仅返回digits、period、remaining_seconds等辅助信息。
常见错误与调用限制
错误码速查表
| 错误码 | 含义 | 常见原因 |
|---|---|---|
| 0 | 成功 | - |
| -1 | 系统内部错误 | 服务异常，可重试 |
| 1001 | 参数错误 | secret非 Base32 格式、period或digits超出范围 |
| 1002 | 认证失败 | 验证码错误、过期或secret与code不匹配 |
| 1003 | 频率限制 | 超过 QPS（20/s）或额度限制 |
| 1004 | 请求体格式错误 | JSON 解析失败 |
调用限制的边界说明
- QPS 20/s：该限制适用于单 IP 或单 API Key。若同时从多个客户端使用同一个 API Key，累计请求不能超过 20 QPS。超出后将返回
1003错误，建议客户端实现本地节流（如令牌桶）和指数退避重试。 - 额度限制：匿名调用与 API Key 调用的每日/每小时额度不同。当额度耗尽时，接口返回
1003错误。额度恢复时间以平台定时刷新为准，通常为下一自然小时或次日。 - batch 操作的消耗：批量请求只计一次请求，但返回三组验证码。这有助于在 QPS 紧张时减少调用次数，但需注意密钥一致性和时间窗口处理。
工程化注意事项
- 密钥分发：
secret是 Base32 字符串，应通过安全通道（如 HTTPS）下发到客户端，并加密存储。切勿硬编码在前端代码中。 - 时钟同步：TOTP 算法依赖客户端和服务器的时钟偏差。建议服务端启用 NTP 同步，并允许 ±1 个周期的时间窗口（通常 ±30 秒）。本 API 内部采用恒定时间比较，客户端自行校验时也应避免时序攻击。
- 限流与重试：对
1003错误采用退避重试策略：首次等待 1 秒，第二次 2 秒，第三次 4 秒，最多重试 3 次。同时记录request_id用于排查。 - 参数校验：在客户端对
secret的长度和 Base32 合法性进行预校验，对period和digits进行范围检查，可提前拦截无效请求。 - 日志监控：将每次调用的
request_id、action、code和耗时记录到日志系统，便于分析调用趋势和异常。 - 批量模式的容错：使用
batch获取三个周期的验证码时，客户端可优先使用当前周期的验证码，若超时则尝试上一个或下一个，提升用户体验。
参考文档
- 官方文档：https://apizero.cn/aidocs/2fa
- 原始 Markdown：https://apizero.cn/aidocs/2fa/raw.md
