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

# Legacy API Key 下架

> 從 sk_ / buzz_live_ 遷移到 Developer Key (dk_) 的操作指引

<Note>
  **狀態：Deprecated** — Legacy API key 目前仍可使用，但 **2026-05-10** 起停止接受。請在那之前完成遷移。
</Note>

## 為什麼要下架

Legacy `sk_`（Project API Key）與 `buzz_live_`（Integration API Key）以明文儲存、僅綁定到 project，無法 audit 到實際使用者。**Developer Key**（`dk_`）以 hash 儲存、綁定到 user 並透過 project membership 控管權限，每次呼叫都能追蹤到人；同一套 key 模型現在已能覆蓋所有對外 API。

維持兩套並行的認證代表每個新 endpoint 都得同時考量兩種情境。把對外認證收斂到 `dk_` 之後，API 介面才能一致，後續也才能加上 per-key scope（會在這次 sunset 之後推出）。

## 時間表

| 階段          | 日期                      | 發生什麼事                                                                                                     |
| ----------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
| Announce    | 2026-04-12              | `dk_` 已能打所有 route。`sk_` / `buzz_live_` 仍可使用。Legacy 路徑的 response 帶上 `Deprecation: true` 與 `Sunset` header。 |
| Deprecation | 2026-04-12 → 2026-05-09 | 遷移期。Legacy key 仍可使用。我們持續監控 legacy 流量。                                                                     |
| Sunset      | **2026-05-10**          | 不再接受 legacy key。使用 legacy key 的請求會回 `401 Unauthorized`。                                                   |
| Removed     | TBD（預計 2026-05-17）      | 移除 legacy code path 與 `ApiKey` 紀錄。本頁保留供查閱。                                                                |

如果到時候 legacy 流量還沒歸零，sunset 日期會再延後；不會提前。

## 哪些東西會在 2026-05-10 停止運作

1. **`sk_...` Project API Key** — 之前在 *Project Settings → API Keys* 建立的 key。
2. **`buzz_live_...` Integration API Key** — 之前在 *Integrations → API* 建立的 key。
3. **`x-api-key` header** — 過去搭配 `sk_` 打舊 `/knowledgebases/*` 路徑的 header。

之後所有對外 endpoint 都只接受 `Authorization: Bearer dk_...`。

## 遷移步驟

### 1. 建立 Developer Key

1. 登入 [app.pathors.com](https://app.pathors.com)。
2. 從帳號選單打開 **Developer Keys**。
3. 點 **Create Key**，名稱建議用對應的整合名稱，**建立當下立刻複製明文 key** — 之後不會再顯示第二次。

Key 屬於建立者本人。請確認該 user 是這個整合會打到的所有 project 的成員。

### 2. 換掉整合裡的 credential

舊用法（2026-05-10 起這幾種都會失敗）：

```bash theme={null}
# sk_ 配 x-api-key header
curl https://api.pathors.com/knowledgebases \
  -H "x-api-key: sk_live_xxx"

# sk_ 配 Authorization: Bearer
curl https://api.pathors.com/knowledgebases \
  -H "Authorization: Bearer sk_live_xxx"

# buzz_live_ 打 completions
curl https://api.pathors.com/project/PROJECT_ID/integration/api/chat/completions \
  -H "Authorization: Bearer buzz_live_xxx"
```

新用法：

```bash theme={null}
# Knowledgebase — 路徑改了
curl https://api.pathors.com/v1/projects/PROJECT_ID/knowledgebases \
  -H "Authorization: Bearer dk_xxx"

# Completions — 路徑不變，只換 key
curl https://api.pathors.com/project/PROJECT_ID/integration/api/chat/completions \
  -H "Authorization: Bearer dk_xxx"
```

兩個重點：

* **Header**：一律用 `Authorization: Bearer`。`x-api-key` header 整個移除。
* **Knowledgebase 路徑**：`/knowledgebases/*` → `/v1/projects/{projectId}/knowledgebases/*`。舊路徑 2026-05-10 起停止接受請求。過去 project 是從 `sk_` 推出來的，改用 `dk_` 之後改在 URL 指定 project。

非 knowledgebase 的 route（completions、sessions、projects、agent config、pathway、tools）路徑不變，只換 key prefix。

### 3. 撤銷舊的 legacy key

`dk_` 在 production 確認可用後，把舊的 legacy key 撤掉，避免不小心 fallback：

1. 打開 **Developer Keys**。
2. 捲到 **Legacy Integration Keys** 區塊（這個區塊只在你還有 legacy key 時顯示）。
3. 每一筆按 **Revoke**，確認 dialog。

撤銷無法 un-revoke，要重來只能再建一把新的 — 所以先確認新 `dk_` 在線上跑得起來再撤舊的。

## 邊界情況

**整合跑在我沒完整控制的服務上（n8n、Zapier、自架 webhook）。**
在該整合的設定 UI 換掉 credential、儲存或重新部署、發一次測試請求。看回應 — 換完之後拿到 401 通常代表新 `dk_` 對該 project 沒權限（重新確認 membership）。

**好幾個整合共用同一把 `sk_`。**
每個整合各建一把 `dk_`。共用是允許的，但 audit log 會混在一起，撤銷一把就會把所有共用整合一起斷掉。

**2026-05-10 之前我看到 response 帶 `Deprecation` / `Sunset` header。**
這是預期的。請求仍然會成功。Header 是在告訴你「你打的這條 route 或這把 key 在 legacy 路徑上」。2026-05-10 之後同樣呼叫會直接 401。

**擁有 `dk_` 的 user 離開 project / 公司。**
該 user 失去 project membership 之後 key 就停止運作。長期整合請把 `dk_` 建在 service account 或穩定的擁有者底下，不要綁在原本的工程師個人帳號。

**`dk_` 看起來正確但回 401。**
依序檢查：prefix 是 `dk_`（不是 `dk_live_`）、header 是 `Authorization: Bearer ...`（不是 `x-api-key`）、key 擁有者是目標 project 的成員、key 沒被撤銷。過期或撤銷的 `dk_` **不會** silent fallback 到 legacy 認證 — 一律 401。

## 需要協助

* **Discord**：[#support](https://discord.gg/e8g86Hqae)
* **Email**：[support@pathors.com](mailto:support@pathors.com)