API Key 管理

给租户的外部系统 / 后端集成发放的长期访问凭证。例如：你公司另一套 CRM 想读知办AI 的知识库、CI 流水线想定时拉文档、Webhook 想往云盘写文件——都用 API Key。给员工本人登录用的不算这里（员工走 SSO / 账号密码登录）。

对外开发者从这里开始

本页是租户场景下的开发者入口。先判断你是哪类接入：

业务场景	用什么	看哪里
CRM / BI / HR / Webhook 等外部系统要读写本租户数据或发送通知	API Key (`ek_`)	本页 + 租户服务端 API 总览
租户自建 Agent Runtime 在对话中实时取知识库 / 云盘 / 组织读取数据	Agent SDK 凭证 → Session Token (`st_`)	Agent SDK 凭证 + 租户自定义 Agent Runtime 接入

进入路径

左侧菜单 凭证与接入 → API Key 管理

概念速览

概念	一句话
API Key	一串长期密钥，用 HTTP 头 `Authorization: Bearer ek_...` 带在请求里。
明文 Secret	完整密钥本身。仅在新建时显示一次，关闭后再也看不到。
Key 前缀	密钥的前几位（如 `ek_a1b2c3d4_******`），用于在列表里识别哪把 Key，不用泄漏完整密钥。
权限范围	这把 Key 能调用的接口范围（如「知识库读取」「云盘读取」），可勾多个。
状态	生效中（绿色，可用）/ 已撤销（灰色，永久不可用）/ 已过期（黄色，过期时间已到）。
过期时间	到期自动转为「已过期」；留空表示永不过期。建议默认设 365 天。

页面一览

截图占位:API Key 管理 — tenant-api-keys-list.png

> 主表 8 列：名称 / Key 前缀 / 权限范围（彩色标签）/ 状态 / 最近使用 / 过期 / 创建 / 操作（撤销按钮）。右上 **+ 新建 Key**。

操作步骤

1. 新建 Key

右上 + 新建 Key → 弹出对话框。
填三个字段：
- 名称：给自己看的备注（如「CRM 同步任务」「BI 拉数据用」）。
- 权限范围：勾选这把 Key 能用的接口范围，至少 1 个：
  - 知识库读取 / 知识库写入 / 知识库管理员
  - 跨用户私有 KB（仅元信息） / 跨用户私有 KB（含内容） — 审计场景专用
  - 云盘读取
- 过期时间：选日期；留空表示永不过期。建议 365 天，到期续。
点创建 → 弹「API Key 创建成功」对话框，仅本次显示明文密钥：
```
ek_a1b2c3d4_QwErTyUiOpAsDfGhJkLzXcVbNm123456
```
点 复制到剪贴板，立刻交给调用方（放到他们系统的环境变量或密钥库里）。关闭弹窗后，明文永远不可恢复。

2. 调用方怎么用

外部系统在每个请求里带这个头：

Authorization: Bearer ek_a1b2c3d4_QwErTyUiOpAsDfGhJkLzXcVbNm123456

接口路径前缀只能用租户对外开放的那套；具体接口清单见租户服务端 API 总览和 API 列表。

2.1 业务场景示例

场景 A：租户 CRM 给员工发知办通知

租户管理员在本页创建一把 API Key，勾选「通知写入」。
CRM 保存 ek_... 到自己的密钥管理系统。
CRM 调 POST /api/external/v1/notifications/agent-conversation，传目标 user_id 和本租户数字员工 agent_id。
知办AI 只在这把 Key 所属租户内解析用户和数字员工，校验通过后发送一条知办数字员工直聊通知。

场景 B：租户自建 Agent 在对话时查知识库

租户管理员创建 Agent SDK 凭证，勾选知识库读取。
Agent 服务用 client_id/client_secret 换 st_，按 expires_in 缓存复用。
Agent 服务用 st_ 调知识库检索接口，为当前会话补充上下文。
st_ 过期或接口返回 401 invalid_session_token 时，再重新换发。

这两类都属于租户侧接入；API Key 只代表创建它的当前租户，不能拿来访问其它租户的数据。

3. 撤销

在 Key 所在行右侧 撤销（垃圾桶图标） → 弹确认框：
「撤销后调用方立即收到鉴权失败，不可恢复，只能新建一把 Key。」
确认后立即生效，列表状态变「已撤销」。

撤销的常见触发：

怀疑密钥泄漏（员工离职、被推到 Git 公开仓库）；
调用方系统下线或迁移；
定期轮换（建议每 90 天一轮，即便没怀疑泄漏）。

4. 过期与续期

设置过期时间的 Key，到期自动转为「已过期」，调用方立即收到鉴权失败。
系统不会自动续期——到期前请新建一把新 Key，发给调用方替换。

字段约束

名称：1-64 字符，非空。
权限范围：至少选 1 个。建议按最小权限勾——只读就别勾管理员。
过期时间：可选；留空 = 永不过期；不能设为过去的日期。

安全注意事项

API Key 只属于创建时所在的当前租户。把 Key 交给调用方前，先确认后台右上角/当前管理范围是目标租户；不要在平台默认租户或错误租户下创建后交给其他租户使用。
明文 Secret 只在创建时显示一次，不会落任何日志 / 数据库 / 备份；系统里只存密钥的不可逆哈希。
把 Key 放到调用方的 环境变量 或 密钥管理服务（Vault / KMS），不要提交到 Git。
给每个调用方一把独立 Key，不要多个系统共用——出事难定位、撤销影响面也大。
怀疑泄漏立刻撤销 + 新建 + 通知调用方更新，不要寄希望于「换一个哈希」。

常见问题

Q：明文 Key 真的找不回吗？ A：找不回。系统只存哈希，明文从创建那一刻起就只剩在你和调用方的剪贴板里。错过这一次只能撤销旧 Key + 新建一把。

Q：撤销后多久生效？ A：立即。调用方下一次请求就会收到 401 invalid api key。

Q：如何排查调用方报「鉴权失败」？ A：到本页列表对照三件事——前缀对不对得上、状态是不是「生效中」、过期时间有没有过；多数情况是其中之一。

Q：调用方报「权限不足」（403）怎么办？ A：那把 Key 的权限范围没勾上目标接口需要的权限。两种修法：在本页编辑权限范围（如果支持）/ 新建一把权限更广的 Key 给调用方替换。

Q：能给某把 Key 改名 / 改过期时间吗？ A：能改名（仅备注），改过期可作软撤销手段（提前过期）。密钥本身（哈希）永不可改——换密钥只能新建。

Q：列表里看到「最近使用」一直是 — 说明什么？ A：说明这把 Key 从来没被用过。结合「创建时间」判断：刚发出去几天还没用很正常；发出去一周以上还没用，要么调用方接错地址、要么没接进去。

API Key 管理 ​

进入路径 ​

概念速览 ​

页面一览 ​

操作步骤 ​

1. 新建 Key ​

2. 调用方怎么用 ​

2.1 业务场景示例 ​

3. 撤销 ​

4. 过期与续期 ​

字段约束 ​

安全注意事项 ​

相关菜单 ​

常见问题 ​