身份认证

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

获取 API Key

登录生产环境网页控制台。
进入 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 的接口权限范围。各接口文章中的购买数量、库存、钱包余额和其他业务约束仍然有效。

IP 白名单

请登录生产环境网页控制台配置用户级 Open API IP 访问白名单。该白名单由同一用户的全部 API Key 共用，不能为单个 Key 分别配置。

白名单关闭时，不限制 Open API 请求的来源 IP。白名单开启后，仅允许来源 IPv4 地址与白名单中任一地址精确匹配的请求；未命中时返回业务错误码 300370。收到该错误码时，请前往网页控制台核对或修改 IP 访问白名单。配置变更最多需要 30 秒生效，切换或修改后请等待生效再验证请求。

请求头

在每个请求中发送单个 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，并完成替换。