API 令牌认证

每个账户最多保留 10 个 API 令牌，在设置页“令牌管理”中创建、重命名、重置、启停或删除。停用仍占名额，删除释放名额；每个令牌均可调用全部公开 API，包括动态代理白名单、提取、地区查询，以及静态住宅查询、采购、续费和改密，无需选择权限。白名单管理不要求来源 IP 已在白名单；动态提取仍校验来源白名单、实名和权益。后台及内部接口不接受该令牌。

生成和重置

1. 登录控制台并进入“账户信息”。
2. 在“API 令牌”卡片确认生成或重置。
3. 复制完整账户令牌并保存到调用方的密钥管理系统。新令牌为 sk- 加 32 位小写十六进制字符，历史 sk_ 令牌继续兼容。

账户本人可随时查看和复制完整令牌，页面不会把它写入本地存储、路由或埋点。重置成功后旧令牌立即失效，所有调用方必须同步替换。

请求认证

每个请求只接受唯一、非空的查询参数 api_key，不接受 Bearer 或 X-API-Key，也不能重复传入同名参数。

curl --get 'https://api.zzhttp.com/openapi/v1/proxy/whitelist/list' \
  --data-urlencode "api_key=$API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'

运行前由密钥管理系统向 API_KEY 注入完整令牌。api_key 会进入查询串，调用方应避免记录完整 URL。

令牌格式错误、Secret 不匹配、令牌禁用或过期、账户不可用时统一返回 HTTP 401，响应不会透露具体是哪一项校验失败。

日志安全

查询参数可能被调用方、代理层、浏览器历史或第三方边缘日志记录，因此必须遵守以下规则：

• 不把包含完整令牌的完整调用 URL 写入应用日志、工单或截图。
• 日志仅保留路由路径、请求 ID、结果码和耗时，不记录查询串。
• 示例只使用运行时变量或首尾保留两位的虚构脱敏值；测试夹具和部署配置不得包含真实令牌。
• 收到完整令牌的响应按敏感数据处理；服务端通过 Cache-Control: no-store 和 Referrer-Policy: no-referrer 降低意外留存风险。

如果怀疑令牌泄露，应立即在控制台重置，并确认旧令牌请求已返回 HTTP 401。