# API 令牌认证

说明账户级 API 令牌的生成、查询参数认证、轮换和日志安全边界。

账户 API 令牌首版仅用于本页列出的三个账户白名单接口，与控制台 Cookie、历史提取 API Link、来源 IPv4 白名单和代理账密互不替代。调用这些白名单接口时，不要求请求来源 IP 已经在白名单中；其他 `/openapi/v1/**` 接口仍按各自文档的认证方式调用。

## 生成和重置

1. 登录控制台并进入“账户信息”。
2. 在“API 令牌”卡片确认生成或重置。
3. 立即复制格式为 `<accessKey>.<secret>` 的完整令牌并保存到调用方的密钥管理系统。

完整令牌只展示一次。关闭弹窗或离开页面后，控制台会清除这段临时内容，也不会把它写入本地存储、路由或埋点。重置成功后旧令牌立即失效，所有调用方必须同步替换。

## 请求认证

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

```bash
curl --get "$API_BASE_URL/openapi/v1/proxy/whitelist/list" \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'
```

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

## 日志安全

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

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

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

html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}