鉴权与 API Key

APIGOTO 的全部业务端点都用同一把 API Key 鉴权。本文说明密钥的格式、在各个端点上的传递方式，以及创建、过期、禁用、泄露处置的完整规则。

密钥格式

API Key 由服务端生成，形如：

api key

sk-rouertcode-<base64url 密文>

sk-rouertcode- 是固定前缀，后半段是 AES-256-GCM 加密后的 base64url 串。密钥本身不含可读信息，不要尝试从中解析用户 ID 或有效期。

🔐

明文只在创建时返回一次

服务端只落库 SHA-256 哈希与前缀（sk-rouertcode- + 6 位字符，共 20 字符）。列表页与详情接口都只能看到前缀，创建弹窗关闭后没有任何途径可以再取回明文。丢了只能删掉重建。

四种传递方式

不同端点接受的密钥位置不同——这是各厂商 SDK 的既有约定，网关照单兼容：

端点	密钥位置	说明
/v1/chat/completions /v1/responses /v1/messages /v1/images/*	Authorization: Bearer <key>	唯一来源，不读其它头
/v1beta/models/*	x-goog-api-key ?key=<key> Authorization: Bearer	按此顺序取，前者命中即停
/api/v1/ai/chat	Rc-Api-Key	平台原生端点，见协议与端点选择
/api/v1/user/*	Authorization: Bearer <JWT>	管理类接口用登录 token，不是 API Key

⚠️

Anthropic SDK 用户注意：不要用 api_key 参数

官方 anthropic SDK 的 api_key= 参数会把密钥放进 x-api-key 头，而 /v1/messages 只读 Authorization: Bearer，会直接返回 40001。请改用 auth_token= 参数，或自己设置 default_headers。

anthropic_ok.py

client = Anthropic(
    base_url="https://www.apigoto.com",
    auth_token=os.environ["APIGOTO_API_KEY"],   # → Authorization: Bearer
)

anthropic_bad.py

client = Anthropic(
    base_url="https://www.apigoto.com",
    api_key=os.environ["APIGOTO_API_KEY"],     # → x-api-key，网关不读 ⇒ 40001
)

创建与管理

密钥在个人后台的「API 密钥」页面管理，也可以直接调用平台管理 API。创建时可以指定：

namestring必填

密钥名称，最长 100 字符。仅用于你自己识别用途。

policy_idnumber可选

绑定的限制策略，决定这把密钥的并发与多档时间窗限额。不传则走账号默认策略，见限流、配额与并发。

expires_atstring可选

过期时间，格式 2026-12-31 23:59:59。留空表示永不过期。格式不合法时按「不设过期」处理，不会报错——所以要自己核对回显。

statusstring可选

初始状态。禁用状态的密钥调用会被网关拒绝。

鉴权失败的四种结果

鉴权是网关的第一道关卡，发生在计费与限流判定之前。四个错误码互相独立，看到哪个就走哪条排查路径：

错误码	HTTP	message	含义与处置
40001	400	api_key is required	请求里根本没带密钥。检查是不是放错了头（见上面的 Anthropic 提示）。
40101	401	api key not found	密钥不存在或已被删除。核对前缀，必要时重建。
40102	401	api key disabled	密钥被手动禁用或被风控停用。去后台查看状态。
40103	401	api key expired	已过 `expires_at`。新建一把并更新配置。

安全建议

永远不要把密钥放进前端代码。浏览器里的密钥等同于公开——任何人打开 DevTools 就能拿走。需要在前端调用时，请自建一层后端代理。
按用途分发密钥，不要全公司共用一把。一把密钥一个用途（生产 / 预发 / 某个同事的本地开发），出问题时可以精确停掉一把而不影响其它。
用环境变量而不是硬编码。硬编码的密钥迟早会被提交进版本库。
怀疑泄露立刻删除重建。删除即时生效，正在进行中的请求也会在下一次鉴权时被拒。不存在「暂时冻结再恢复」的软手段——就该重建。
给密钥设过期时间。临时用途的密钥设一个短过期，比依赖「记得回来删」可靠。

💡

上游厂商的密钥不用交给我们

如果你走 BYOK（自带厂商凭证），厂商密钥保存在你自己的凭证配置里，调用时仍然用 APIGOTO 的 API Key 鉴权。终端不需要、也不应该同时持有两套密钥。