Skip to main content

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.

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

​
為什麼要下架

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 之後推出）。

​
時間表

階段日期發生什麼事
Announce2026-04-12dk_ 已能打所有 route。sk_ / buzz_live_ 仍可使用。Legacy 路徑的 response 帶上 Deprecation: true 與 Sunset header。
Deprecation2026-04-12 → 2026-05-09遷移期。Legacy key 仍可使用。我們持續監控 legacy 流量。
Sunset2026-05-10不再接受 legacy key。使用 legacy key 的請求會回 401 Unauthorized。
RemovedTBD（預計 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。
  2. 從帳號選單打開 Developer Keys。
  3. 點 Create Key，名稱建議用對應的整合名稱，建立當下立刻複製明文 key — 之後不會再顯示第二次。
Key 屬於建立者本人。請確認該 user 是這個整合會打到的所有 project 的成員。

​
2. 換掉整合裡的 credential

舊用法（2026-05-10 起這幾種都會失敗）： 
# 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"
新用法： 
# 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。

​
需要協助