鉴权与密钥

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

创建密钥

打开控制台,进入 API 密钥。
创建密钥并起一个事后认得出的名字(例如 prod-backend 或 local-dev)。
复制密钥并妥善保存。完整密钥只在创建时显示一次 —— RouteMux 只保存它的哈希, 之后无法再显示。如果丢失,请新建一把密钥并撤销旧的。

密钥只放服务端

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

发送密钥

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

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

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

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

只发其中一个。多个密钥头携带不同凭据时会被拒绝，返回 AUTH_AMBIGUOUS_API_KEY（HTTP 400）。缺少密钥时按入口协议的错误格式返回 AUTH_API_KEY_REQUIRED（HTTP 401）。

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

限制与轮换

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

允许的模型

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

过期时间

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

撤销

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

轮换

新建一把密钥,把客户端切过去,再撤销旧的。账号里每新建一把密钥,我们都会发邮件提醒你。

常见鉴权错误

错误码	HTTP	含义
`AUTH_API_KEY_REQUIRED`	401	没有发送密钥头。
`AUTH_INVALID_API_KEY`	401	密钥不存在或已撤销。
`AUTH_AMBIGUOUS_API_KEY`	400	多个密钥头携带了不同凭据。
`AUTH_ACCOUNT_SUSPENDED`	403	所属账号不能发起请求。

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