# 身份验证

发往 `https://api.stack.foldbun.com` 的每个请求都须在 `Authorization` 请求头中携带 API 密钥。

```http
Authorization: Bearer fbs_...
```

密钥在[控制台](https://stack.foldbun.com/console/keys)创建，归属于账户而不是个人。使用账户的任一密钥发起的调用，均计入该账户。

## 邮箱验证

新账户需先验证邮箱，账户的密钥才能调用 API。验证前，调用会返回 `403 email_unverified`。

## 密钥格式

密钥由前缀 `fbs_` 加 49 个 base62 字符组成，共 53 个字符。最后 6 个字符为校验和，因此输入错误或随意编造的密钥会在任何查询之前以 `401 unauthorized` 拒绝。

系统只保存密钥的 SHA-256 哈希。密钥在创建时显示一次，之后无法再次显示。丢失的密钥无法找回；应创建新密钥并吊销旧密钥。

## 模型范围

密钥可限定为所选模型。范围的格式为 `model:<id>`，例如 `model:ppocr-v6`。

- 不带模型范围的密钥，可调用账户有权使用的所有模型。
- 带有一个或多个 `model:<id>` 范围的密钥，只能调用这些模型。调用其他模型会以 `403 model_locked` 拒绝。

范围只会收窄密钥的权限，不会扩大。账户所在的模型池决定哪些模型可用。详见[速率限制与模型池](https://stack.foldbun.com/zh/docs/rate-limits/)。

## 有效期

创建密钥时可设置有效期：永不过期、7、30、90 或 365 天，或未来的自定义日期。已有密钥的有效期之后可以修改或清除。过期或已吊销的密钥会以 `401 unauthorized` 拒绝。

## 吊销与轮换

- **吊销** 使密钥立即失效。
- **替换** 创建一个名称和范围相同的新密钥，并将旧密钥设为在宽限期后过期，宽限期最长 7 天。替换不会延长旧密钥原有的较早有效期。不设宽限期时，旧密钥立即失效。

已部署密钥的轮换步骤：

1. 在控制台中替换密钥并设置宽限期。
2. 部署新密钥。
3. 等待旧密钥过期，或在部署完成后吊销。

## 限制

- 一个账户最多可有 100 个有效密钥。
- 密钥名称为 1 至 64 个字符。
- 密钥的最近使用时间显示在控制台中。

## 失败情形

| 状态码 | 错误码 | 含义 |
|---|---|---|
| 401 | `unauthorized` | 请求头缺失或格式错误，或密钥无效、已过期、已吊销。 |
| 403 | `model_locked` | 密钥的范围或账户所在的模型池不允许使用该模型。 |
| 403 | `email_unverified` | 密钥所有者尚未验证邮箱。 |

错误信封的格式详见[错误](https://stack.foldbun.com/zh/docs/errors/)。