Subotiz OpenAPI 使用 API Key 进行身份验证。每次请求都需要在 HTTP 请求头中携带有效的 API Key，网关会对其进行校验，通过后才会将请求转发至后端服务。
获取 API Key
登录 Subotiz 商家后台，进入 设置 > 开发者设置 页面，即可查看和管理你的 API Key。
注意： API Key 仅在创建时完整显示一次，请妥善保存。若遗失，需重新生成（原 Key 将立即失效）。
发起鉴权请求
请求头格式
所有 OpenAPI 请求都必须在 HTTP 请求头中包含以下字段：
| 请求头 | 值 | 说明 |
|---|---|---|
Authorization | Bearer {your_api_key} | 将 {your_api_key} 替换为你的实际 API Key |
示例
curl -X GET "https://api.subotiz.com/openapi/v1/orders" \
-H "Authorization: Bearer {your_api_key}"密钥轮换
当密钥存在泄露风险或需要定期更新时，可以在开发者设置页面对密钥进行轮换。
轮换流程
- 在开发者设置页面发起密钥轮换，系统将生成一个新的 API Key
- 系统为旧 Key 设置过渡期（默认 3 分钟，可在轮换时自定义）
- 在过渡期内，新旧 Key 均可通过鉴权，请尽快将你的服务切换至新 Key
- 过渡期结束后，旧 Key 自动失效，仅新 Key 有效
注意： 请在旧 Key 失效前完成服务切换，避免请求中断。如果你配置了 Webhook，密钥轮换同样会影响 Webhook 的签名验证，建议在过渡期内同时支持新旧两个密钥验签，详见 Webhook 概述。
错误处理
当鉴权失败时，接口将返回 HTTP 401 状态码。以下是常见错误原因及处理建议：
| 错误原因 | 处理建议 |
|---|---|
请求未携带 Authorization 头 | 确认请求头中包含 Authorization: Bearer {key} |
| API Key 无效或不存在 | 确认 Key 是否正确，或从后台重新获取 |
| API Key 已过期或被撤销 | 在开发者设置中重新生成 Key |
Authorization 格式错误 | 确保格式为 Bearer {key}，注意 Bearer 后有且仅有一个空格 |
错误响应示例：
{
"code": "unauthorizedError",
"message": "ApiKey authentication is required"
}