# API 密钥与认证

API 密钥用于 CI、服务端和无人值守的 REST 或 MCP 自动化。人类 CLI 和远端 MCP 默认使用浏览器授权。

## 创建 API 密钥

API 密钥从 [TokST Web 仪表盘](https://tokst.com/dashboard)创建。

1. 登录仪表盘
2. 在侧边栏导航到 **API 密钥**
3. 点击 **创建密钥**
4. 为密钥指定一个描述性名称（例如："Development"、"CI Pipeline"、"Agent Claude"）
5. 立即复制密钥——它仅显示一次

### 密钥格式

```
tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

前缀 `tk_live_` 标识其为生产密钥。所有密钥均遵循此格式，不论套餐为何。

## 密钥存储

当您创建密钥时，TokST 在服务端存储其 **SHA-256 哈希值**。原始密钥永远不会存储——如果您丢失了它，必须吊销并创建一个新密钥。

在本地，CLI 将凭证存储在 `~/.tokst/config.json` 中：

```json
{
  "apiKey": "tk_live_xxxx",
  "accessToken": "eyJhbGci...",
  "anonKey": "sb_publishable_xxxx",
  "tokenExpiresAt": "2026-07-09T10:57:47.306Z",
  "supabaseUrl": "https://pdjpdivokmcevxdrvtfb.supabase.co",
  "apiKeyId": "c699987e-..."
}
```

MCP 服务器读取同一文件进行认证。

## 认证流程

### 面向人和本地智能体的浏览器设置

```bash
curl -fsSL https://tokst.com/install.sh | bash
```

该脚本会下载通过 SHA-256 校验的 TokST 独立 CLI，然后打开 TokST 完成授权。它只需要 Unix 终端和 `curl`。

### 面向自动化的 API 密钥登录

```bash
tokst login --key tk_live_xxxx
```

流程如下：

1. CLI 将 API 密钥发送到 TokST API
2. 服务器验证 SHA-256 哈希值是否与存储的密钥匹配
3. 成功后，服务器返回 **JWT 访问令牌**（有效期为 1 小时）
4. CLI 将 API 密钥和 JWT 都存储在 `~/.tokst/config.json` 中
5. 后续 API 调用使用 JWT，并会在过期前自动刷新

### 令牌生命周期

| 令牌 | 时长 | 刷新 |
|---|---|---|
| JWT 访问令牌 | 1 小时 | 由 CLI 和 MCP 服务器自动刷新 |

您通常无需担心令牌过期问题——CLI 和 MCP 服务器会自动处理刷新。

## 速率限制

Edge 服务路由使用滚动的每用户频率限制：

| 限制 | 值 |
|---|---|
| 认证交换 | 每分钟 10 次请求 |
| 用量记录 | 每分钟 60 次请求 |
| 嵌入生成 | 每分钟 30 次请求 |
| 上传 URL 请求 | 每分钟 30 次请求 |

超过这些限制会返回 HTTP 429（请求过多）。速率限制在滚动 60 秒窗口内重置。

## 月度配额

使用量按用户计入月度配额，不同套餐有所不同。计数采用原子递增，并发智能体调用不会相互覆盖：

| 套餐 | 月度操作数 | 存储 |
|---|---|---|
| **免费版** | 1,000 | 500 MB |
| **入门版** | 2,000 | 2 GB |
| **专业版** | 10,000 | 10 GB |
| **团队工作区** | 20,000 共享 | 20 GB 共享 |
| **Legacy Max / Team** | 保留原有权益 | 保留原有权益 |

随时检查您的使用情况：

```bash
tokst status
tokst status --json    # 供程序化使用
```

## 吊销与删除密钥

| 操作 | 效果 |
|---|---|
| **吊销** | 密钥立即停用。无法重新启用。此密钥已颁发的现有令牌在到期前仍然有效。 |
| **删除** | 密钥被永久移除。所有关联的令牌立即失效。 |

在仪表盘中，使用**吊销**可立即永久停用密钥并保留审计记录；使用**删除**可移除密钥记录。

## 用量与按密钥审计日志

月配额计数归属于用户，API 密钥日志记录每个操作使用的密钥。仪表盘显示：

- 当月总操作数
- 按日统计的操作数（图表）
- 最后使用时间戳
- 密钥名称和创建日期

这将配额执行与按密钥的审计归因分离。

## MCP 服务器自动认证

MCP 服务器通过读取 `~/.tokst/config.json` 自动进行认证。无需环境变量或手动配置步骤——它会从 `tokst login` 创建的同一文件中获取凭证。

要覆盖默认认证，请设置 `TOKST_API_KEY` 环境变量：

```bash
TOKST_API_KEY=tk_live_xxxx bun x -y @tokst/mcp-server
```

## 安全最佳实践

- **使用描述性密钥名称**，以便在仪表盘中识别其用途
- **为开发、生产以及每个智能体/集成创建单独的密钥**
- **定期轮换密钥**，方法是创建新密钥、更新您的集成，然后吊销旧密钥
- **永远不要将密钥提交到版本控制**——使用环境变量或密钥管理器
- **通过仪表盘定期检查使用情况**，以检测意外活动
- **立即从仪表盘吊销被泄露的密钥**

## 智能体快速设置

要为 AI 智能体（Claude Code、Cursor、Codex、ZCode 等）授予 TokST 访问权限，只需分享一个链接：

```
https://tokst.com/skill.md
```

智能体读取该文档后会自行安装 TokST 技能——CLI、技能文件和 MCP 配置——到自己的 skills 目录。文档内置版本检查，重新读取该链接即可自动更新到最新版本。

您也可以在仪表盘的 **API 密钥** 页面直接复制现成的安装脚本或 SKILL.md（点击任意密钥旁的 **Copy for Agent**）。