适用场景2FA 动态验证码TOTP是双因子认证的核心技术广泛应用于登录验证、交易确认、敏感操作授权等场景。该 API 基于 RFC 6238 标准兼容 Google Authenticator 等主流身份验证器支持生成、校验和批量三种操作模式。在工程集成中开发者需要重点关注接口的调用频率限制和额度边界以确保生产环境的稳定性和合规性。接口能力边界核心指标请求方法POST端点https://v1.apizero.cn/api/2fa最大 QPS20 次/秒基于单个 IP 或单一 API Key额度差异匿名调用不带 Authorization 头与携带 API Key 的调用各自拥有独立的每日/每小时额度上限具体数值以平台文档为准。操作模式generate生成当前周期的动态码verify校验用户输入的验证码batch返回上一个周期、当前周期和下一个周期的验证码共三组适合客户端容错场景参数边界参数类型必填说明约束范围secretstring是Base32 编码的 TOTP 密钥自动忽略空格与连字符不区分大小写长度至少 16 字符128 位actionstring否操作类型默认行为取决于是否同时提供code。若只传secret则视为generate若同时传secret和code则视为verifygenerate/verify/batchcodestring条件当actionverify或未显式指定action但提供了code时必填4~8 位数字periodnumber否验证码有效期秒10~120默认 30digitsnumber否验证码位数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 Keycurl -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 } }字段含义字段类型说明codeint业务码0 表示成功非 0 表示错误msgstring结果描述request_idstring请求唯一标识用于日志追踪data.totp_codestring当前周期的验证码generate/batch模式返回verify模式成功时不返回此字段data.digitsint实际使用的验证码位数data.periodint实际使用的有效期秒data.remaining_secondsint当前周期剩余秒数data.next_refreshstring下一次刷新时间的 ISO 格式data.timestampint服务端当前 Unix 时间戳秒verify模式下若校验成功data中不包含totp_code仅返回digits、period、remaining_seconds等辅助信息。常见错误与调用限制错误码速查表错误码含义常见原因0成功--1系统内部错误服务异常可重试1001参数错误secret非 Base32 格式、period或digits超出范围1002认证失败验证码错误、过期或secret与code不匹配1003频率限制超过 QPS20/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原始 Markdownhttps://apizero.cn/aidocs/2fa/raw.md