API Key 与管理 API

管理后台“安全 > API Key”用于给第三方系统开放 AIHelms 管理 API。例如，企业内部系统可以使用它读取人员、模型或资源信息，并按授权接口执行管理操作。

使用前确认

管理 API Key 权限等同管理员。创建前应确认：

• 对接系统由企业管理，并且有明确负责人。
• Key 只保存在服务端，不会下发到浏览器、桌面客户端或移动端。
• 已确定用途、调用来源、有效期和停用流程。
• 不把同一个 Key 分给多个无法区分的系统。

新建 API Key

进入“安全 > API Key”，点击“新建 API Key”。

填写以下内容：

点击“创建”后，列表会显示新 Key。立即复制到对接系统的密钥存储中，不要写进代码仓库、配置样例或工单正文。

请求管理 API

AIHelms 管理 API 的基础路径通常是：

http://<AIHelms 地址>/api/v1

在请求头中使用：

Authorization: Bearer <管理 API Key>

下面的示例读取供应商列表，用于确认 Key 和地址是否正确：

curl "http://<AIHelms 地址>/api/v1/providers?page=1&page_size=20" \
  -H "Authorization: Bearer <管理 API Key>"

成功时返回 code、message 和 data。具体字段以当前部署版本的接口文档为准。

查看接口文档

浏览器打开：

http://<AIHelms 地址>/api/docs

在接口文档页面点击“Authorize”，输入管理 API Key，再选择接口进行测试。测试创建、修改和删除类接口时，先使用非生产数据，并记录测试对象。

状态与有效期

API Key 列表显示：

• 当前状态：启用、禁用或已过期。
• 创建时间。
• 最后使用时间。
• 过期时间。

“最后使用”长期为空时，先确认对接系统是否真的发送了该 Key，以及请求是否到达当前 AIHelms 环境。

禁用和删除

临时停用

点击“禁用”后，使用该 Key 的新请求会被拒绝。故障排查、系统下线或发现异常来源时，优先禁用，确认无影响后再决定是否删除。

永久删除

删除前确认对接系统已经换用新 Key 或停止调用。删除后无法恢复，所有仍使用旧 Key 的请求都会失败。

轮换 Key

1. 新建一个用途相同的新 Key。
2. 把新 Key 更新到对接系统。
3. 观察新 Key 的“最后使用”时间。
4. 禁用旧 Key 并确认业务正常。
5. 删除旧 Key。

常见问题

模型调用所需的 Key 请查看用户指南，不要使用本页的管理 API Key。