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

# 认证与配置

> 获取 API Key、请求认证、通用请求头与安全最佳实践

## 获取 API Key

调用 API 前需要先获取 API Key：

1. 登录 bizyair.ai
2. 进入 **API Keys**
3. 点击 **创建新 Key**，输入别名（如 `production` / `dev-local`）
4. 复制生成的 Key（**仅显示一次**，请妥善保存）

<Warning>
  API Key 是账号的唯一凭据，泄露后他人可消耗你的账户余额。切勿提交到 Git、写入前端代码或分享到公开渠道。
</Warning>

请求认证

所有 API 请求需在 HTTP Header 中携带 `Authorization` 字段：

```http theme={null}
Authorization: Bearer $BIZYAIR_API_KEY
```

示例：

```bash theme={null}
curl -H "Authorization: Bearer $BIZYAIR_API_KEY" \
     "https://api.bizyair.ai/x/v1/user/metadata"
```

如 Key 缺失或无效，返回 401：

```json theme={null}
{"error": "UNAUTHORIZED", "code": "401", "message": "缺少认证信息"}
```

## 通用请求头

以下请求头适用于所有调用方式，部分 Header 用于控制调用模式：

| 请求头                            | 必填            | 说明                                        |
| ------------------------------ | ------------- | ----------------------------------------- |
| `Authorization`                | ✅ 是           | `Bearer $BIZYAIR_API_KEY` 格式              |
| `Content-Type`                 | ✅ 是（POST/PUT） | 固定 `application/json`                     |
| `X-Bizyair-Task-Async`         | ❌ 否           | 设为 `enable` 启用异步查询模式                      |
| `X-BizyAir-Task-WebHook-Url`   | ❌ 否           | 设置回调 URL 启用 WebHook 模式                    |
| `X-BizyAir-Task-Authorization` | ❌ 否           | 自定义回调请求的 `Authorization` 头，用于验证回调来源       |
| `X-Bizyair-Task-*`             | ❌ 否           | 任何以此前缀开头的 Header 会**原样透传**到 WebHook 回调请求中 |

<Note>
  当同时设置 `X-Bizyair-Task-Async: enable` 与 `X-BizyAir-Task-WebHook-Url` 时，**WebHook 模式优先**，异步查询标识被忽略。
</Note>

## 安全最佳实践

| 场景      | 推荐做法                       | 禁忌                 |
| ------- | -------------------------- | ------------------ |
| 服务端     | 存入环境变量 / 密钥管理服务            | ❌ 写入源码             |
| 前端（浏览器） | 通过你自己的后端代理转发               | ❌ 直接放入 `fetch` 请求头 |
| 移动端     | 通过你自己的后端中转                 | ❌ 打包进 App 二进制      |
| 开源项目    | 用 `.env` 文件 + `.gitignore` | ❌ 提交 `.env` 到仓库    |
| 团队协作    | 每人独立 Key，定期轮换              | ❌ 共用同一个 Key        |
| 怀疑泄露    | 立即在个人中心禁用并创建新 Key          | ❌ 期望没人发现           |