鉴权与密钥

每个网关请求都用一把 OneHop API 密钥鉴权。密钥绑定到你的账号、从预付费钱包扣费, 可随时在 Platform 控制台查看明文、加限制或撤销。

创建密钥

打开控制台,进入 API 密钥。
创建密钥并起一个事后认得出的名字(例如 prod-backend 或 local-dev)。
复制密钥。OneHop 以可逆方式存储密钥,所以之后也能在同一页面重新查看明文 —— 方便 cc-switch 这类工具。

密钥只放服务端

把密钥当密码对待。绝不要写进客户端代码或提交到代码仓库。优先用环境变量,例如 ONEHOP_API_KEY。

发送密钥

OneHop 接受你的 SDK 本来就会发的请求头,按协议家族区分:

# 兼容 OpenAI(多数客户端推荐)
Authorization: Bearer $ONEHOP_API_KEY

# 兼容 Anthropic
x-api-key: $ONEHOP_API_KEY

# 兼容 Google GenAI / Vertex
x-goog-api-key: $ONEHOP_API_KEY

只发其中一个。同时发两个密钥头会被拒绝,返回 AMBIGUOUS_API_KEY(HTTP 400)。缺少密钥时按入口协议的错误格式返回 401。

curl https://api.onehop.ai/v1/chat/completions \
  -H "Authorization: Bearer $ONEHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "ping" }]
  }'

限制与轮换

密钥可以带护栏,让泄漏的凭据影响面有限:

允许的模型

把密钥限定到一部分模型。请求其它模型会被拒绝,而不是被扣费。

过期时间

为短期或临时集成设置过期日期。

撤销

在控制台立即撤销密钥。撤销后的密钥下次请求会返回 INVALID_API_KEY。

重新查看明文

无需轮换即可重新查看已有密钥的明文。

常见鉴权错误

错误码	HTTP	含义
`API_KEY_REQUIRED`	401	没有发密钥头。
`INVALID_API_KEY`	401	密钥不存在或已撤销。
`AMBIGUOUS_API_KEY`	400	同时发了多个密钥头。
`USER_BLOCKED`	403	所属账号已被禁用。

完整错误契约见限流与错误。