> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub.jerrylu.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API 认证

> 使用 Bearer token 格式的 Developer API Key 调用开放 API。

# API 认证

开放 API 使用 Developer API Key。请求时把 key 放在 `Authorization` header 里。

```bash theme={null}
curl https://your-site.example/api/v1/subscriptions \
  -H "Authorization: Bearer subm_your_key_here"
```

## Header 格式

```text theme={null}
Authorization: Bearer <api-key>
```

缺少 header、格式错误、key 不存在或 key 已撤销时，API 会返回 `401 Unauthorized`。

## Key 归属

API Key 绑定到创建它的用户。所有订阅查询、创建、更新和删除都会限制在这个用户范围内。

## 权限范围（Scopes）

每个 API Key 带有 scopes，用来限定它能做什么：

| 范围      | 允许                                 |
| ------- | ---------------------------------- |
| `read`  | 查询、读取订阅；调用分析与审计端点                  |
| `write` | 在 `read` 基础上，额外允许创建、更新、取消、暂停、恢复和删除 |

`read` 始终存在。新建 Key 默认同时拥有 `read` 和 `write`。如果要创建只读 Key（适合只做分析、绝不应修改数据的 Agent），在创建 Key 时传入 `scopes` 数组：

```json theme={null}
{ "name": "Analysis agent", "scopes": ["read"] }
```

用只读 Key 执行写操作会返回 `403 insufficient_scope`。返回的 Key 对象会包含其 `scopes`。

## 安全建议

* 不要把 API Key 提交到代码仓库。
* 不要在浏览器前端硬编码 Developer API Key。
* 给脚本或 Agent 使用专用 key，方便撤销。
* 怀疑泄露时立即删除旧 key 并重新创建。

## 失败认证限流

认证失败也会被限流，避免无效 key 或爆破请求消耗系统资源。默认值可以用 `API_FAILED_AUTH_RATE_LIMIT_PER_HOUR` 调整。