API Key
租户级服务端集成凭证，用于 Open API 签发 contextToken 与知识库同步等能力
简述
API Key 是面向 外部业务系统 的租户级服务端凭证（格式 sk-odk-...）。您的后端、实施脚本或自动化任务携带 Key 调用 OpenDesk Open API（如签发 Web SDK 上下文 Token、同步知识库目录与文档）。Key 仅保存在服务器，完整字符串 创建或轮换时仅展示一次。
权限说明： 仅 超级管理员 可管理 API Key；不可通过 角色管理 授权给其他员工。
功能位置
在管理后台侧边栏「全局设置」分组下打开「API Key」（独立于 系统设置 菜单项）。页面展示 Key 列表与 新建 API Key 按钮。
配置与规则
列表字段
| 列 | 说明 |
|---|---|
| 名称 | 创建时填写，便于识别调用方（如「官网后端」「知识库同步脚本」） |
| API Key | 脱敏展示（如 sk-odk-live-****...），不可 再次查看完整 Key |
| 状态 | 启用 / 禁用 |
| 创建时间 | Key 首次创建时间 |
| 最近使用时间 | 最近一次成功调用 Open API 的时间；便于排查是否仍在使用 |
新建 API Key
- 点击 新建 API Key，填写名称（2～40 字）。
- 创建成功后弹出 一次性展示 窗口，显示完整
sk-odk-...。 - 立即复制 到密钥管理系统；关闭窗口后 无法再次查看。
- 页面提示：请勿将 Key 写入前端代码、Git 仓库或移动端安装包。
日常维护
| 操作 | 说明 |
|---|---|
| 禁用 | 脚本停用、人员离职或怀疑泄露时使用；禁用后 Open API 立即 不可用 |
| 启用 | 恢复已禁用的 Key |
| 轮换 | 生成新 Key 并替换旧哈希；旧 Key 立即失效，须同步更新所有调用方 |
| 删除 | 须先 禁用，再删除记录；删除后不可恢复 |
禁用、启用、轮换、删除均须二次确认。
注意事项
- API Key 绑定 租户，不代表某个员工身份；调用 Open API 时 无需 再传租户 ID。
- 当前 Key 无细粒度 scope：同一租户下任一启用 Key 均可调用已开放的 Open API（传递客户上下文、知识库 API 等）。
- 生产与测试环境请使用 不同 Key；不再使用的 Key 请禁用并删除。
- 完整 Key 不会出现在操作日志中；请关注 最近使用时间 发现异常调用。
与其他功能的关系
- Open API · 传递客户上下文：使用 Key 调用
POST /api/v1/open/context-token签发contextToken。 - Open API · 知识库 API：使用同一套 Key 管理知识库目录与文档。
- 渠道管理 / Web SDK：访客侧 不 使用 API Key；Key 仅用于您的业务后端。
- 角色管理：不提供 API Key 相关权限项；仅超管可操作。
业务场景示例
官网后端对接客户上下文
角色与目标： 开发人员在会员中心后端集成 OpenDesk，访客打开 Web SDK 前自动同步会员等级与订单号。
系统配置： 超管在 API Key 新建 Key「官网 BFF」，复制完整 Key 配置到后端环境变量。
场景效果： 后端调用 Open API 签发 contextToken 并交给 Web SDK；坐席在工作台看到同步后的客户资料与会话纪要。技术细节见 Open API · 传递客户上下文。