身份认证

所有 /open-api/v1/** 接口都使用 API Key 认证。API Key 通过网页控制台管理，不通过本文档中的接口创建或修改。

获取 API Key

1. 登录对应环境的网页控制台。
2. 进入 API Key 管理页面。
3. 创建 API Key，并设置便于识别的名称和到期时间。
4. 立即安全保存完整 API Key。完整值只在创建成功时显示一次。

测试环境与生产环境的 API Key 不应混用。

环境	网页控制台	API Key 管理
测试环境	打开测试控制台	管理测试 API Key
生产环境	打开生产控制台	管理生产 API Key

权限范围

API Key 只能访问本文档中的 Open API，不能用于访问网页控制台接口。API Key 是通用凭证：当前不支持为单个 Key 配置细分接口权限、IP 白名单或采购额度。每个有效 API Key 都可以访问所属账号下全部已开放的 Open API 能力。

因此，应将每个 API Key 视为可访问账号下全部已开放 Open API 的最高权限凭证进行保护。按使用场景创建多个 Key 可以便于识别、轮换和吊销，但不会缩小单个 Key 的接口权限范围。各接口文章中的购买数量、库存、钱包余额和其他业务约束仍然有效。

请求头

在每个请求中发送单个 X-API-Key 请求头：

X-API-Key: <YOUR_API_KEY>

API Key 的格式为 pt- 加 43 位 URL-safe 字符，总长度为 46 个字符。不要在 Query、请求体或 Cookie 中传递 API Key。

认证失败

当请求到达 Open API 且正常生成认证失败响应时，HTTP 状态为 200，响应体中的 code 为 400001：

{
  "code": 400001,
  "msg": "Authentication failed.",
  "data": null,
  "next": null
}

出于安全考虑，响应不会指出具体失败原因。请在网页控制台检查 Key 状态和到期时间；如无法确认，可重新创建 Key 并替换调用方配置。

安全建议

• 仅在调用方服务端保存和使用 API Key。
• 使用密钥管理能力或受保护的环境变量保存，不写入代码仓库。
• 不在日志中打印完整请求头。
• 可按使用场景分别创建 Key，以便识别和轮换；这不会缩小 Key 的权限范围。
• 怀疑泄露时立即吊销原 Key，并完成替换。