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。

​
需要帮助