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

# 鉴权

> 使用 Bearer Token 鉴权 Yelu AI API 请求，并在不同环境中安全管理 API Key。

Yelu 使用 HTTP `Authorization` Header 中的 API Key 鉴权所有兼容 OpenAI 的请求。

## Bearer 鉴权

每个请求都应携带：

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer $YELU_API_KEY
```

<CodeGroup>
  ```bash Curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.yelu.ai/v1/models', {
    headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}` },
  });
  if (!response.ok) throw new Error(`鉴权失败：${response.status}`);
  console.log(await response.json());
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.get(
      "https://api.yelu.ai/v1/models",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

## 密钥生命周期

<Steps>
  <Step title="为不同应用创建独立密钥">开发、测试、生产以及不同工作负载应使用不同 Key，便于轮换、归因和限制。</Step>
  <Step title="使用 Secret Store">将 Key 保存在密钥管理器或受保护的环境变量中，只授予必要工作负载读取权限。</Step>
  <Step title="定期轮换">先创建并部署新 Key，验证流量后再撤销旧 Key。</Step>
  <Step title="泄露后立即撤销">Key 一旦出现在仓库、日志、截图或浏览器包中，应立即撤销。删除可见副本并不足够。</Step>
</Steps>

## 只能在服务端使用

<Warning>
  不要在浏览器或移动端直接使用长期有效的 Yelu Key。客户端应调用你自己的已鉴权后端，再由后端调用 Yelu。
</Warning>

后端应验证最终用户身份与权限、限制模型和预算、校验输入、约束输出长度，并按隐私政策处理日志。

## 常见鉴权错误

| 状态码   | 含义                    | 处理方式                         |
| ----- | --------------------- | ---------------------------- |
| `401` | Key 缺失、格式错误、无效、过期或已停用 | 检查 Header，必要时轮换 Key          |
| `403` | 账号、Key、IP、分组或资源无权限    | 检查 Dashboard 中的限制与模型权限       |
| `429` | 账号或分组达到请求限制           | 按[速率限制](/zh/rate-limits)退避重试 |

错误响应使用兼容 OpenAI 的 `error` 对象，详见[错误处理](/zh/errors)。