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

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

鉴权格式

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

Authorization: Bearer <YOUR_API_KEY>

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

完整请求示例

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

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"}]}'

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

鉴权错误响应

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

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

错误响应体示例：

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

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

安全建议

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

设置环境变量的示例：

# Linux / macOS
export HHAPI_API_KEY="<YOUR_API_KEY>"
export API_BASE_URL="<API_BASE_URL>"

在代码中读取：

import os

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

const apiKey = process.env.HHAPI_API_KEY;
const apiBase = process.env.API_BASE_URL;

​鉴权格式

​完整请求示例

​鉴权错误响应

​安全建议

鉴权格式

完整请求示例

鉴权错误响应

安全建议