> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# 认证

> API Key、请求头、服务端代理和 Key 轮换

JoyToken 使用 API Key 认证。模型调用必须在服务端发送，并使用对应兼容接口的认证 Header。

## 通用请求头

| 通用 Header      | 必填 | 说明                 |
| -------------- | -- | ------------------ |
| `Content-Type` | 是  | `application/json` |
| `X-Request-ID` | 建议 | 日志、账单和排障关联         |

> **Warning**
>
> 不要同时传 `Authorization` 和 `X-API-Key`。如果两个都存在，当前网关会优先读取 `X-API-Key`。

## 选择协议接口

#### OpenAI

认证 Header：

```text
Authorization: Bearer $JOY_TOKEN_API_KEY
```

`POST /openai/v1/responses` 和 `POST /openai/v1/chat/completions` 使用相同的认证 Header。

运行示例前，先从 [环境](/zh/user-guide/environments) 选择并设置 `JOY_TOKEN_OPENAI_BASE_URL`。

```bash
curl "$JOY_TOKEN_OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: auth-example-001" \
  -d '{
    "model": "auto",
    "input": "ping"
  }'
```

#### Anthropic

认证 Header：

```text
x-api-key: $JOY_TOKEN_API_KEY
```

运行示例前，先从 [环境](/zh/user-guide/environments) 选择并设置 `JOY_TOKEN_ANTHROPIC_BASE_URL`。

```bash
curl "$JOY_TOKEN_ANTHROPIC_BASE_URL/messages" \
  -H "x-api-key: $JOY_TOKEN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "ping" }],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

## 服务端代理

浏览器和移动端不要直接持有 JoyToken API Key。推荐结构：

```text
Browser / App -> Your backend -> JoyToken
```

#### OpenAI

```ts
export async function POST(req: Request) {
  const body = await req.json();
  const baseUrl = process.env.JOY_TOKEN_OPENAI_BASE_URL;

  const response = await fetch(`${baseUrl}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.JOY_TOKEN_API_KEY}`,
      "X-Request-ID": crypto.randomUUID(),
    },
    body: JSON.stringify(body),
  });

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}
```

如需代理 Responses API，将相同的认证请求发送到 `${baseUrl}/responses`。上游路径应固定在服务端代码中，不要接收浏览器传入的任意路径。

#### Anthropic

```ts
export async function POST(req: Request) {
  const body = await req.json();
  const baseUrl = process.env.JOY_TOKEN_ANTHROPIC_BASE_URL;

  const response = await fetch(`${baseUrl}/messages`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.JOY_TOKEN_API_KEY ?? "",
      "X-Request-ID": crypto.randomUUID(),
    },
    body: JSON.stringify(body),
  });

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}
```

## 认证后还会检查

| 检查               | 失败响应                        |
| ---------------- | --------------------------- |
| Key 是否有效和 active | `403 invalid_api_key`       |
| IP、tier、模型策略     | `403 policy_rejected`       |
| 钱包余额和 Key 预算     | `402 insufficient_quota`    |
| 请求体合法性           | `400 invalid_request_error` |

## 轮换 API Key

1. 创建新 Key，并绑定同样或更严格的策略。
2. 写入服务端 secret manager 或环境变量。
3. 用新 Key 发一条带 `X-Request-ID` 的验证请求。
4. 在 JoyToken Console 确认新 Key 有日志和用量。
5. 禁用或 revoke 旧 Key。

## 安全建议

| 做法                 | 原因             |
| ------------------ | -------------- |
| 每个应用和环境一把 Key      | 方便预算、策略和用量归因   |
| 测试 Key 设置预算和 tier  | 控制成本           |
| 高风险 agent 使用独立 Key | 避免无人值守任务消耗过高   |
| 泄露后直接 revoke       | 不要尝试继续使用泄露 Key |