跳到主要内容

🔑 API Keys

为脚本、机器人和集成提供对 Open WebUI 的程序化访问。

API Keys 是个人访问 Token，允许外部代码调用 Web UI 使用的相同接口。您在浏览器中可以执行的任何操作 —— 聊天生成、模型列表获取、文件上传、RAG 查询 —— 您的脚本都可以通过单个 Authorization: Bearer 请求头来完成。每个 Key 都继承了创建它的用户的权限，因此无需学习单独的权限模型。

为什么需要 API Keys？​

无需浏览器的自动化​

脚本、CI/CD Pipeline、监控机器人和第三方工具都需要程序化访问。API Keys 为它们提供了一个稳定的凭证，不会随浏览器会话过期而失效。

相同的权限，不同的界面​

API Key 代表了您本人。它继承了您的角色和用户组权限 —— 适用于 Web UI 的相同访问控制也适用于每个 API 请求。

可撤销且可审计​

为每个 Key 命名以描述其用途（例如“CI Pipeline”、“监控机器人”）以便于跟踪使用情况。如果 Key 泄露，可以立即删除它 —— 无需重置密码，无需使会话失效，只需单击一下即可。

关键功能​

🔐 Bearer Token 认证标准的 Authorization: Bearer 请求头，可用于任何 HTTP 客户端或 SDK
🛡️ 限定于用户Key 继承创建用户的角色和用户组权限
🚫 端点限制可选择限制该 Key 可访问的 API 路由
👥 权限控制需要全局管理员开关，非管理员用户还需要单独的用户组功能权限

入门指南​

步骤 1：全局启用 API Keys（管理员）​

  1. 以管理员身份登录
  2. 打开 Admin Panel > Settings > General
  3. 滚动到 Authentication 部分
  4. 开启 Enable API Keys 开关
  5. 点击 Save
信息

这是全局总开关。当它关闭时，任何人（包括管理员）都无法生成 Key。当它开启时：

  • 管理员用户可以立即生成 Key
  • 非管理员用户仍需要 API Keys 功能权限（步骤 2）

(可选) 启用 API Key Endpoint Restrictions 以限制 API Keys 可以调用的路由。以逗号分隔的列表形式指定允许的端点（例如 /api/v1/models,/api/v1/chat/completions）。

步骤 2：授予非管理员用户权限（管理员）​

非管理员用户需要 API Keys 功能权限。使用以下任一方法进行授予：

选项 A：默认权限（所有用户）​

  1. Admin Panel > Users > Groups > Default Permissions
  2. 在 Features Permissions 下，开启 API Keys 开关
  3. 点击 Save
注意

这将授予具有 "user" 角色的每个用户生成 API Keys 的能力。为了进行更严格的控制，请使用选项 B。

选项 B：用户组（特定用户）​

  1. Admin Panel > Users > Groups
  2. 选择或创建一个用户组（例如 "API Users"）
  3. 在 Permissions > Features Permissions 下，开启 API Keys 开关
  4. 点击 Save
提示

创建一个专用的 "API Users" 或 "Monitoring" 组，并仅添加需要程序化访问的账户。这遵循了最小权限原则。

步骤 3：生成 Key​

  1. 点击您的个人头像（左下角侧边栏）
  2. 选择 Settings > Account
  3. 在 API Keys 部分，点击 Generate New API Key
  4. 给它一个描述性的名称（例如“监控机器人”）
  5. 立即复制该 Key —— 您将无法再次查看它
注意

请像对待密码一样对待 API Keys。将它们存储在密码管理器中，千万不要将它们提交到版本控制中，也不要在公共渠道中分享它们。如果 Key 泄露，请立即将其删除并生成一个新的。

使用您的 API Key​

将 Key 作为 Bearer Token 在 Authorization 请求头中传递：

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())

有关完整的端点参考 —— 聊天生成、Ollama 代理、RAG、文件管理等 —— 请参阅 API Endpoints。

在消耗 Authorization 的反向代理之后？​

如果 Open WebUI 位于一个使用 Authorization 请求头进行自身认证（如 Basic 认证、SSO Sidecar、公司 API 网关、双向 TLS 适配器等）的网关后面，客户端可以通过专用的请求头传递 API Key。中间件会按以下顺序进行检查：Authorization: Bearer、token cookie，以及可配置的自定义请求头。

自定义请求头默认为 x-api-key，管理员可以通过 CUSTOM_API_KEY_HEADER 环境变量重命名它，以避免与请求链中的其他任何内容冲突。

curl -H "X-OpenWebUI-Key: YOUR_API_KEY" \
  http://openwebui.internal/api/models
# Open WebUI 容器环境变量
CUSTOM_API_KEY_HEADER=X-OpenWebUI-Key

最佳实践​

专用服务账户​

专门为自动化创建一个非管理员用户（例如 monitoring-bot、ci-pipeline）。从该账户生成 Key。如果 Key 泄露，攻击者也只能获得该用户的权限 —— 而不是管理员权限。

端点限制​

启用 API Key Endpoint Restrictions，并且仅白名单您的集成实际需要的路由。监控机器人只需要 /api/models 和 /api/chat/completions —— 不要让它访问 /api/v1/files/ 或管理员端点。

Key 轮换​

定期删除旧 Key 并生成新 Key，特别是对于长期运行的集成。使用日期或版本命名 Key 以跟踪轮换（如 "Monitoring Bot - 2025-Q1"）。

故障排除​

在 Settings > Account 中看不到 API Keys 部分？

  • 检查全局开关： 验证管理员是否已在 Admin Panel > Settings > General > Enable API Keys 中启用了 API Keys。参见 ENABLE_API_KEYS。
  • 检查您的权限（非管理员用户）： 验证您的账户或用户组是否在 Features Permissions 下拥有 API Keys 功能权限。参见 USER_PERMISSIONS_FEATURES_API_KEYS。

收到 401 Unauthorized 响应？

  • 验证 Key 的格式是否正确：Authorization: Bearer sk-...
  • 检查该 Key 是否已被删除
  • 如果启用了端点限制，请确认您调用的路由是否在允许列表中

局限性​

创建后无法查看​

API Keys 在创建后无法再次查看。如果您丢失了 Key，请将其删除并生成一个新的。

没有单 Key 的独立权限​

Key 会继承创建它的用户的完整权限。您无法将 Key 限制为其次级所有者权限的子集（端点限制除外）。

没有自动过期机制​

API Keys 不会自动过期。您必须手动删除并轮换它们。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.