管理用户 API Key

什么时候用

需要给用户、外部系统或开发者提供 API 访问凭据时——无论是调用 OpenAI 兼容接口、使用智能体还是访问其他 API，都需要 API Key。每个用户可以拥有多个 API Key，并设置一个默认 Key。

你需要准备

• 管理员权限（admin 可以管理所有用户的 API Key）
• 已创建的用户（见上一章）
• 一个有意义的 Key 名称（例如：生产环境、测试环境、第三方系统等）

普通用户需联系管理员创建 API Key。

操作步骤

第 1 步：进入用户管理

左侧菜单 -> 用户管理。

在用户列表中找到要管理 API Key 的用户，点击右侧「更多」下拉菜单，选择「API Key」。

第 2 步：新增 API Key

在弹出的「API Key 管理」对话框中：

1. 点击右上角「新增 API Key」按钮
2. 在「新增 API Key」表单中填写 Key 名称
3. 点击「确定」

重要提示：API Key 明文只在创建时显示一次。请立即复制并保存到安全的地方，丢失后无法找回，只能重新创建。

第 3 步：认识 API Key 格式

API Key 以 sk-u- 开头，后面是随机字符串。

列表中展示的是 Key 的前 12 个字符，用于识别不同的 Key，完整 Key 只在创建时显示。

第 4 步：设置默认 Key

每个用户可以有多个 API Key，但同一时间只能有一个默认 Key：

• 在 Key 列表中，「默认」列显示星号图标
• 点击非默认 Key 的星号图标，将其设为默认
• 创建第一个 Key 时会自动设为默认

设为默认 Key 后，该用户之前的默认 Key 会自动取消默认状态。

第 5 步：删除 API Key

在 Key 列表中点击「删除」链接，确认后 Key 将永久失效。

删除 Key 会立即终止使用该 Key 的所有 API 调用，请谨慎操作。

怎么验证成功了

1. 在「API Key 管理」对话框中能看到刚创建的 Key
2. 复制刚创建的完整 Key，调用 /openai/v1/models 接口，能正常返回模型列表
3. 在 Key 列表中能看到「最后使用」时间更新（需要实际调用一次 API）

常见问题

忘记保存 API Key 怎么办？

没有任何方式可以找回已创建的 API Key。系统只保存必要的校验信息，不会明文保存你的 Key。请删除旧 Key 并创建新的。

API Key 调用返回 401 认证失败

请检查：

1. 使用的是完整 Key（不是只显示前缀的列表项）
2. Key 没有被删除或禁用
3. 用户账号没有被禁用
4. 请求地址正确：OpenAI 兼容接口使用 https://www.aimatespace.com/openai/v1

Key 名称可以修改吗？

当前版本不支持修改 Key 名称。如需改名，请删除旧 Key 并创建新的。

API Key 失效处理

如果 API Key 失效或泄漏，请立即：

1. 删除失效/泄漏的 Key：在 API Key 管理列表中点击「删除」，立即终止该 Key 的所有访问
2. 创建新的 Key：生成新的 API Key 并重新配置到你的应用或系统中
3. 检查使用记录：如果是泄漏，建议检查该 Key 的使用记录，确认是否有异常访问

紧急情况：如果发现 Key 被滥用，应先删除 Key 阻断访问，再调查和重建。

深入

核心概念

API Key

• 格式：sk-u- + 随机字符串
• 后端存储：仅存安全校验信息 + 前 12 字符前缀
• 创建时只展示一次明文，丢失无法找回
• 每个用户可以有多个 API Key，但同一时间只能有一把是默认 Key
• 创建第一把 Key 时自动设为默认
• 设置某把 Key 为默认，会先取消该用户其它 Key 的默认状态

安全审计

以下操作会记录安全事件：

常见坑

1. API Key 不可恢复

   忘记保存创建时的 API Key，没有任何方式可以找回。只能重新创建一把新的。

2. 设默认 Key 会影响其它 Key

   把 Key B 设为默认后，Key A 的默认状态会被自动取消。这个行为不需要手动操作，但需要注意应用可能绑定了旧的默认 Key。

• 想了解如何创建用户？见 创建用户并分配智能体
• 想了解如何配置用户模型白名单？见 配置用户模型白名单