API Key 使用说明

API Key 用于以当前用户身份调用系统接口，适合脚本、自动化任务或第三方系统集成场景。

本文只介绍用户侧的 API Key 管理与使用方式，不展开其他个人资料设置项。

使用前提

从 2026-03-26 起，用户中心的 API Key 功能增加了独立权限点控制。

• 权限点标识：user.api_key.manage
• 角色配置入口：角色管理 -> 选择目标角色 -> 系统配置 -> 系统管理
• 权限点名称：管理用户APIKey

如果当前用户的角色没有分配该权限点：

• 个人资料页左侧不会显示 API Key 管理 入口
• 直接请求 GET /user_api_key、POST /user_api_key、PUT /user_api_key/:id、DELETE /user_api_key/:id 也会被后端拒绝

超级管理员默认仍可使用该功能。

进入 API Key 页面

登录成功后会进入工作台或项目列表页，右上角可以看到当前登录用户入口。

1. 点击右上角用户名称
2. 在展开菜单中点击“修改资料”

当角色已分配 user.api_key.manage 权限点时，进入个人资料页后，左侧会看到“基本信息”和“API Key 管理”两个入口。

1. 点击左侧“API Key 管理”
2. 进入“我的 API Key”页面

API Key 列表说明

API Key 列表页会展示当前用户创建过的所有 Key，包含以下信息：

• 名称：创建时填写的标识名称，方便后续区分用途
• Key：默认只显示脱敏后的内容
• 状态：启用或禁用
• 操作：查看、复制、启用/禁用、删除

创建 API Key

1. 点击页面右上角“新建 API Key”
2. 在弹窗中填写名称
3. 点击“确认”

创建成功后，系统会弹出完整 Key。

• 该完整 Key 只会完整展示一次
• 需要立即复制并保存到安全位置
• 关闭弹窗后，列表中只会继续显示脱敏值

查看与复制 API Key

如果后续需要再次确认某个 Key，可在列表中点击“查看”图标打开展示弹窗，再点击“复制 key”完成复制。

建议做法：

• 使用创建时的名称区分不同用途
• 复制后立即保存到安全的密码库或配置中心
• 不要把真实 Key 直接发送到群聊或工单中

启用、禁用、删除 API Key

禁用 API Key

点击列表中的“禁用”按钮后，Key 会立即变为禁用状态。禁用后的 Key 无法继续调用接口。

需要恢复使用时，点击“启用”即可重新生效。

删除 API Key

点击“删除”后，系统会弹出确认框。确认删除后，该 Key 会被永久移除，后续不能再恢复使用。

使用 API Key 调用接口

API Key 支持两种传递方式。

方式一：Bearer Token

将 Key 放到请求头 Authorization 中：

curl -H "Authorization: Bearer <your_api_key>" \
  "http://127.0.0.1:10010/api/user_api_key"

方式二：Query 参数

将 Key 作为 api_key 或 apiKey 参数传入：

curl "http://127.0.0.1:10010/api/user_api_key?api_key=<your_api_key>"

curl "http://127.0.0.1:10010/api/user_api_key?apiKey=<your_api_key>"

实测结果：

• 启用中的有效 Key 可以正常访问接口
• 禁用后的 Key 会返回 401
• 删除后的 Key 也会返回不可用结果

注意事项

• 完整 Key 只建议在创建成功时保存一次
• 列表页默认展示的是脱敏值，不适合作为实际调用参数
• 建议按用途命名，例如“jenkins-deploy”“local-debug”“report-job”
• 如果某个 Key 不再使用，优先禁用或删除，避免长期暴露
• Bearer 和 query 两种方式都可用，但推荐优先使用 Bearer 请求头
• 如果页面中看不到 API Key 管理 入口，优先检查当前角色是否已分配 管理用户APIKey 权限点

已知差异说明

本文以 API Key 功能为准进行说明。

在某些运行环境中，个人资料页可能还会出现其他历史功能入口或残留资源。如果看到与本文无关的入口，可忽略，不影响 API Key 的正常使用。