# 认证与 API Key

> 怎么带 Key、一把 Key 能管住什么、泄露了怎么办。

来源：https://www.scirouter.cn/docs/authentication · 更新于 2026-09-23

所有 `/v1` 接口都用 API Key 认证，放在 `Authorization` 请求头里：

```http
Authorization: Bearer <你的 API Key>
```

- **只认这一种写法。** Cookie、查询参数、`api-key` 头都不认。
  浏览器里即使登录着 SciRouter，会话 Cookie 也不会被当成调用凭据——网关收到 `/v1` 请求时会直接丢掉 Cookie 头，
  所以别的网页没法借你的登录态替你调模型、花你的额度。
- Key 的明文以 `sk-sr-` 开头，共 46 位。格式不对的请求直接 401 `unauthenticated`。

## 新建时可以设什么

在[控制台的 API Keys 页面](https://www.scirouter.cn/console/keys)新建。每一项都是这把 Key 自己的边界：

| 设置 | 作用 | 越界时 |
|---|---|---|
| 名称 | 给你自己看；建好后不能改 | — |
| 允许的模型 | 白名单，留空表示不限 | 403 `model_not_allowed`；`/v1/models` 也只列白名单里的 |
| 月度额度上限 | 这把 Key 每月最多花多少，不填表示不限 | 429 `key_quota_exceeded`，下个月恢复 |
| 过期时间 | 到期自动失效，不填表示不过期 | 401 `key_expired` |
| 归属项目 | 团队工作区里按项目归账；项目可以设月预算 | 429 `project_budget_exceeded` |

明文**只在创建时显示一次**，我们只存它的哈希。关掉那个窗口之后就再也拿不到了——
请当场复制，存进密钥管理工具或环境变量。

## 放进环境变量，不要写进代码

```bash
export SCIROUTER_API_KEY="<创建时复制的那串>"
```

官方 OpenAI SDK（Python 与 Node）会读 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL` 两个环境变量。
已有的代码不想改一行的话，把这两个变量指向 SciRouter 即可：

```bash
export OPENAI_API_KEY="$SCIROUTER_API_KEY"
export OPENAI_BASE_URL="https://api.scirouter.cn/v1"
```

## 不要放进前端

`/v1` 的 CORS 对所有来源开放（不带凭证），技术上浏览器可以直接调——
但那等于把 Key 发给每一个打开网页的人，任何人都能从开发者工具里拿走它。
浏览器、App、小程序里的调用，请经你自己的后端转发。

[Playground](https://www.scirouter.cn/playground) 和站内对话是例外：它们走的是登录会话，不经过 API Key。

## 一个用途一把 Key

按服务、环境、实验分开建，好处是三样：

- 泄露时只吊销那一把，别的服务不受影响；
- 用量与日志按 Key 分开看，谁花的钱一目了然；
- 白名单和额度上限可以按用途设——跑批量评测的那把设一个月度上限，失控时最多花掉这么多。

同一把 Key 下还想再细分（比如十个实验共用一把），用请求体里的 `metadata` 贴标签，见「可观测性」。

## 泄露了怎么办

在控制台**吊销**它：立即生效、不可撤销，正在用它的服务会开始收到 401 `key_revoked`。
然后新建一把换上。

没有「暂停」开关。一把已经泄露的 Key 不存在「先停一下观察观察」——停用期间它仍然是一把有效的钥匙。

## 一次调用会经过哪些检查

按顺序：

1. **认证**：Key 存在、没吊销、没过期；
2. **授权**：模型在 Key 的白名单里，也在你的套餐里；
3. **额度**：Key 的月度上限、套餐的日上限、项目的月预算；
4. **限频**：每分钟请求数、每分钟 token 数（按估算）、并发数，Key 与账号各算一份；
5. **预扣**：按估算成本先冻结一笔额度，调用结束后按实际用量结算，多退少补。

第 5 步意味着：余额很少时，一个 `max_tokens` 设得很大的请求可能因为**预扣不够**而被拒（402 `insufficient_quota`，`details.required_quota` 是这次要冻结的额度），
哪怕它实际只会用掉一点。调小 `max_tokens` 或充值即可。

每一步的余量都能看到：限频余量在响应头 `x-ratelimit-*` 里，额度在控制台——见「可观测性」。