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