认证 | JoyToken | Documentation

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

通用请求头

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

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

选择协议接口

OpenAI

Anthropic

认证 Header：

Authorization: Bearer $JOY_TOKEN_API_KEY

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

运行示例前，先从环境选择并设置 JOY_TOKEN_OPENAI_BASE_URL。

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

服务端代理

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

Browser / App -> Your backend -> JoyToken

OpenAI

Anthropic

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。上游路径应固定在服务端代码中，不要接收浏览器传入的任意路径。

认证后还会检查

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

轮换 API Key

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

安全建议

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