接口鉴权与安全

开放接口 Token

/open/* 只接受独立接口令牌。使用以下任一请求头：

X-Api-Token: YOUR_TOKEN

或：

Authorization: Bearer YOUR_TOKEN

不要把 Token 放进查询字符串。URL 容易进入浏览器历史、代理日志、统计系统和截图。

curl 示例

curl -fsS \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://search.example.com/open/disk/list?page=1&size=20'

建议通过受限环境变量或秘密管理工具向程序提供 Token，不要直接写进脚本仓库：

curl -fsS \
  -H "Authorization: Bearer $JUZHENPAN_API_TOKEN" \
  'https://search.example.com/open/disk/list?page=1&size=20'

权限边界

• /v1 的公开读取不等于允许批量抓取或绕过访问限制；
• /auth/v1 需要终端用户会话；
• /admin/v1 只允许管理员，不能使用开放接口 Token 代替；
• /open 令牌通常具有导入或同步能力，应按生产秘密保护。

轮换和泄露处理

怀疑 Token 泄露时：

1. 立即在后台生成或配置新令牌；
2. 更新所有合法调用方；
3. 验证新令牌工作；
4. 停用旧令牌；
5. 检查相关访问和操作日志；
6. 从代码、CI 日志和工单附件中移除泄露值。

不要只删除聊天消息就认为泄露已经解除。

调用方要求

• 使用 HTTPS；
• 设置连接和整体请求超时；
• 对写操作建立业务幂等或去重策略；
• 不对 401/403、参数错误和授权拒绝盲目重试；
• 遵守分页、大小和频率上限；
• 日志中掩码请求头和敏感业务内容。