🔑 API 密钥

给脚本、机器人和外部集成使用的 OPL 数据空间程序化访问令牌。

API Key 是个人访问令牌，让外部代码调用与 Web UI 相同的接口。你能在浏览器里做的事情，例如聊天补全、模型列表、文件上传、RAG 查询，脚本基本都可以通过一条 Authorization: Bearer 请求头完成。每个 Key 都继承创建者的权限，所以没有另一套需要单独学习的权限模型。

组织与 API Key

在组织感知部署中，API Key 会继承调用者当前角色，以及服务端根据其当前归属组织解析出的授权规则。请把 Key 当作用户凭据，而不是租户范围的共享密钥。如果某个用户切换了组织，或者失去了某些访问权限，就不能再假设旧 Key 还能访问同样的数据。

---

为什么需要 API 密钥

让自动化摆脱浏览器

脚本、CI/CD pipeline、监控机器人和第三方工具都需要程序化访问。API Key 提供了稳定凭据，不会像浏览器 session 一样随会话结束而失效。

同一套权限，不同的调用入口

API Key 的行为就像“你本人”。它继承你的角色和用户组权限，因此 Web UI 的所有访问控制都会自动套用到 API 请求。

可撤销、可追踪

你可以给每个 Key 起有意义的名字，例如 “CI Pipeline” 或 “Monitoring Bot”，方便追踪用途。如果 Key 泄露，也不需要重置密码，只要删除该 Key 即可。

---

关键能力

🔐 Bearer Token 认证	标准 Authorization: Bearer 头，适配任意 HTTP 客户端或 SDK
🛡️ 绑定用户作用域	Key 继承创建者的角色与用户组权限
🚫 端点限制	可选只允许某些 API 路由被 Key 调用
👥 权限门控	对非管理员而言，需要全局开关 + 每组功能权限共同允许

---

开始使用

步骤 1：管理员全局启用 API 密钥

1. 使用 administrator 账号登录
2. 打开 管理面板 > 设置 > 通用
3. 找到 Authentication 区域
4. 打开 启用 API 密钥
5. 点击 保存

信息

这是总开关。关闭时，任何人都无法生成 Key；开启后：

• 管理员 用户可以立即生成
• 非管理员 仍需要额外拥有 API 密钥功能权限

你还可以选择启用 API 密钥端点限制，并用逗号分隔方式写出允许访问的路由，例如 /api/v1/models,/api/v1/chat/completions。

步骤 2：给非管理员授予 API 密钥权限

非管理员需要显式拥有 API 密钥 功能权限。

方案 A：默认权限（所有用户）

1. 进入 管理面板 > 用户 > 用户组 > 默认权限
2. 在 功能权限 中打开 API 密钥
3. 点击 保存

注意

这会让所有 user 角色用户都能生成 API Key。如果你需要更紧的控制，请改用方案 B。

方案 B：按用户组授权

1. 打开 管理面板 > 用户 > 用户组
2. 选择或创建一个用户组，例如 “API Users”
3. 在 权限 > 功能权限 中打开 API 密钥
4. 点击 保存

提示

推荐单独创建 “API Users” 或 “Monitoring” 之类的组，只把真正需要程序化访问的账号放进去。

步骤 3：生成 Key

1. 点击左下角 profile icon
2. 打开 设置 > 账户
3. 在 API 密钥 区域点击 生成新的 API 密钥
4. 给它起一个描述性名称
5. 立即复制 Key，后面无法再次查看明文

注意

把 API Key 当成密码处理。放进 secrets manager，不要提交到版本库，也不要发到公开频道。一旦泄露，立即删除并重新生成。

---

如何使用

把 Key 作为 Bearer Token 放进请求头：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/api/models

import requests

response = requests.get(
    "http://localhost:8080/api/models",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response.json())

完整接口说明请查看 API Endpoints。

如果前置代理会吞掉 Authorization 头怎么办

如果 OPL 数据空间前面还有会消费 Authorization 请求头的网关或代理，例如 Basic Auth、SSO sidecar、企业 API gateway 或 mTLS 适配器，客户端也可以通过单独的自定义请求头传递 API Key。

默认自定义头是 x-api-key，管理员也可以通过 CUSTOM_API_KEY_HEADER 修改名称。

curl -H "X-OpenWebUI-Key: YOUR_API_KEY" \
  http://openwebui.internal/api/models

CUSTOM_API_KEY_HEADER=X-OpenWebUI-Key

---

最佳实践

使用专用服务账号

为自动化创建一个非管理员用户，例如 monitoring-bot 或 ci-pipeline，然后从这个账号下生成 Key。即便泄露，攻击者也只能获得该账号权限，而不是管理员权限。

在组织化部署里，应尽量把服务账号放在它实际服务的组织中；只有确实需要跨组织能力时，才考虑使用清晰文档化的全局管理员自动化账号。

启用端点限制

打开 API Key Endpoint Restrictions，只允许某个集成真正需要的路由。例如监控机器人可能只需要 /api/models 和 /api/chat/completions，就没必要让它访问文件上传或管理员接口。

定期轮换

长期运行的集成建议定期删除旧 Key 并生成新 Key。可以在命名里带上日期或版本，方便追踪轮换周期。

---

故障排查

账户页里看不到 API 密钥区块？

• 先检查全局开关是否已启用：Enable API Keys
• 如果你不是管理员，确认账号或用户组已拥有 API 密钥 功能权限

收到 401 Unauthorized？

• 确认格式是 Authorization: Bearer sk-...
• 确认 Key 没有被删除
• 如果启用了路由限制，确认当前访问的端点已被列入 allowlist

---

限制

创建后无法再次查看

API Key 生成后不能再次查看明文。丢失后只能删除并重新生成。

不能为单个 Key 再做更细粒度权限切分

Key 会继承创建者的完整权限，除了端点限制外，不能再单独给某个 Key 缩减成更小权限子集。

不会自动过期

API Key 不会自动失效，需要你手动删除与轮换。