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

# HHAPI API 鉴权方式：Bearer Token 格式、401/403 错误与安全使用最佳实践

> HHAPI 所有接口均通过 HTTP Authorization 请求头传递 Bearer Token 进行身份鉴权。本文介绍鉴权请求头的标准格式、401 未授权与 403 禁止访问两种错误码的含义，以及使用环境变量安全存储和使用 API Key 的最佳实践。

HHAPI 使用基于 HTTP Header 的 Bearer Token 鉴权机制。每次调用接口时，需要在请求头中携带通过控制台创建的 API Key。服务端会对每个请求进行鉴权验证，密钥缺失、格式错误或失效均会导致请求被拒绝并返回相应错误码。

## 鉴权格式

在所有 HTTP 请求头中加入以下字段：

```http theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

其中 `<YOUR_API_KEY>` 替换为您在控制台创建的实际密钥字符串。

## 完整请求示例

以下是一个从环境变量读取 API Key 并携带鉴权头的完整 `curl` 请求示例：

```bash theme={null}
curl "$API_BASE_URL/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HHAPI_API_KEY" \
  -d '{"model": "<MODEL_ID>", "messages": [{"role": "user", "content": "Hello"}]}'
```

<Note>
  示例中 `$HHAPI_API_KEY` 和 `$API_BASE_URL` 均从环境变量读取。请勿将真实密钥直接写入代码或脚本，具体设置方法参见下方[安全建议](#安全建议)。
</Note>

## 鉴权错误响应

当鉴权失败时，API 会返回以下错误状态码：

| 状态码 | 含义 | 常见原因 |
| - | - | - |
| `401` | 未授权 | API Key 缺失、格式错误或已失效 |
| `403` | 禁止访问 | API Key 有效，但无权限访问目标资源 |

错误响应体示例：

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

<Note>
  API Key 在控制台（`<CONSOLE_URL>`）中创建和管理。请妥善保管您的密钥，不要将其提交到代码仓库或暴露在客户端代码中。如需获取或轮换密钥，请前往 [控制台 API Key 管理页面](/api-key)。
</Note>

## 安全建议

<Tip>
  建议将 API Key 存储在服务端环境变量中（如 `HHAPI_API_KEY`），通过后端代理转发请求，避免密钥直接暴露在前端或移动端代码中。
</Tip>

设置环境变量的示例：

```bash theme={null}
# Linux / macOS
export HHAPI_API_KEY="<YOUR_API_KEY>"
export API_BASE_URL="<API_BASE_URL>"
```

在代码中读取：

```python theme={null}
import os

api_key = os.environ.get("HHAPI_API_KEY")
api_base = os.environ.get("API_BASE_URL")
```

```javascript theme={null}
const apiKey = process.env.HHAPI_API_KEY;
const apiBase = process.env.API_BASE_URL;
```