API 密钥与认证

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

创建 API 密钥

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

密钥格式

tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

密钥存储

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

在本地，CLI 将凭证存储在 ~/.tokst/config.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 服务器读取同一文件进行认证。

认证流程

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

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

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

面向自动化的 API 密钥登录

tokst login --key tk_live_xxxx

流程如下：

CLI 将 API 密钥发送到 TokST API
服务器验证 SHA-256 哈希值是否与存储的密钥匹配
成功后，服务器返回 JWT 访问令牌（有效期为 1 小时）
CLI 将 API 密钥和 JWT 都存储在 ~/.tokst/config.json 中
后续 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	保留原有权益	保留原有权益

随时检查您的使用情况：

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

吊销与删除密钥

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

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

用量与按密钥审计日志

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

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

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

MCP 服务器自动认证

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

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

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）。