> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 鉴权

Subotiz OpenAPI 使用 **API Key** 进行身份验证。每次请求都需要在 HTTP 请求头中携带有效的 API Key，网关会对其进行校验，通过后才会将请求转发至后端服务。

## 获取 API Key

登录 Subotiz 商家后台，进入 **设置 > 开发者设置** 页面，即可查看和管理您的 API Key。

<Warning>
  API Key 仅在创建时完整显示一次，请妥善保存。若遗失，需重新生成（原 Key 将立即失效）。
</Warning>

<Frame>
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/11cb1758-071e05a71c7a4b71335e20998b59f98375fa0fa062fb6514b7d1395e-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=2b43e8d811cbe7dfb051a7ab8da00abd" width="1907" height="757" data-path="images/11cb1758-071e05a71c7a4b71335e20998b59f98375fa0fa062fb6514b7d1395e-image.png" />
</Frame>

## 发起鉴权请求

### 请求头格式

所有 OpenAPI 请求都必须在 HTTP 请求头中包含以下字段：

| 请求头             | 值                       | 说明                                 |
| --------------- | ----------------------- | ---------------------------------- |
| `Authorization` | `Bearer {your_api_key}` | 将 `{your_api_key}` 替换为您的实际 API Key |

### 示例

```bash theme={null}
curl -X GET "https://api.subotiz.com/openapi/v1/orders" \
  -H "Authorization: Bearer {your_api_key}"
```

## 密钥轮换

当密钥存在泄露风险或需要定期更新时，可以在开发者设置页面对密钥进行**轮换**。

### 轮换流程

1. 在开发者设置页面发起密钥轮换，系统将生成一个新的 API Key
2. 系统为旧 Key 设置过渡期（默认 3 分钟，可在轮换时自定义）
3. 在过渡期内，**新旧 Key 均可通过鉴权**，请尽快将您的服务切换至新 Key
4. 过渡期结束后，旧 Key 自动失效，仅新 Key 有效

<Warning>
  请在旧 Key 失效前完成服务切换，避免请求中断。如果您配置了 Webhook，密钥轮换同样会影响 Webhook 的签名验证，建议在过渡期内同时支持新旧两个密钥验签，详见 [Webhook 概述](/zh/webhook/introduction-2)。
</Warning>

## 错误处理

当鉴权失败时，接口将返回 HTTP `401` 状态码。以下是常见错误原因及处理建议：

| 错误原因                    | 处理建议                                       |
| ----------------------- | ------------------------------------------ |
| 请求未携带 `Authorization` 头 | 确认请求头中包含 `Authorization: Bearer {key}`     |
| API Key 无效或不存在          | 确认 Key 是否正确，或从后台重新获取                       |
| API Key 已过期或被撤销         | 在开发者设置中重新生成 Key                            |
| `Authorization` 格式错误    | 确保格式为 `Bearer {key}`，注意 `Bearer` 后有且仅有一个空格 |

### 错误响应示例

```json theme={null}
{
  "code": "unauthorizedError",
  "message": "ApiKey authentication is required"
}
```