认证 | JoyToken | Documentation

JoyToken 使用 API Key 认证。模型调用必须在服务端发送，并使用 Bearer token。

请求头

Header	必填	说明
`Authorization`	是	`Bearer $JOY_TOKEN_API_KEY`
`Content-Type`	是	`application/json`
`X-Request-ID`	建议	日志、账单和排障关联
`X-API-Key`	可选	兼容旧客户端，不建议新接入默认使用

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

cURL 示例

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

$ curl "$JOY_TOKEN_OPENAI_BASE_URL/chat/completions" \
>   -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -H "X-Request-ID: auth-example-001" \
>   -d '{
>     "model": "auto",
>     "messages": [{ "role": "user", "content": "ping" }]
>   }'

服务端代理

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

Browser / App -> Your backend -> JoyToken

1 export async function POST(req: Request) {
2   const body = await req.json();
3   const openAIBaseUrl = process.env.JOY_TOKEN_OPENAI_BASE_URL;
4 
5   const response = await fetch(`${openAIBaseUrl}/chat/completions`, {
6     method: "POST",
7     headers: {
8       "Content-Type": "application/json",
9       Authorization: `Bearer ${process.env.JOY_TOKEN_API_KEY}`,
10       "X-Request-ID": crypto.randomUUID(),
11     },
12     body: JSON.stringify(body),
13   });
14 
15   return new Response(response.body, {
16     status: response.status,
17     headers: response.headers,
18   });
19 }

认证后还会检查

检查	失败响应
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