Dify API 401 invalid api key 怎么解决？
简答：Dify API 返回 401 invalid api key，通常不是“多重试几次”能解决，而是凭据类型、Authorization 请求头、请求端点或自托管密钥不匹配。先确认你调用的是应用 Service API、知识库 API，还是模型供应商插件；然后用最小请求验证 Key，最后再检查 Base URL、区域和 Docker 环境变量。本文为 onomeo 的第三方技术整理，不是 Dify 官方页面。
定义：Dify API 的 401 invalid api key，指服务端未接受当前请求中的认证凭据，常见原因包括 Key 类型错误、Bearer 格式错误、Key 已失效、端点不匹配或自托管实例的密钥配置发生变化。
先做这张判断表：你拿错的是哪一种 Key？
不要先修改模型名或反复重试。先根据请求路径和报错位置判断认证对象；Dify 的 Service API 使用 Bearer API Key，而控制台接口、Web API 和模型供应商插件可能使用不同的认证上下文。
| 出现 401 的位置 | 优先检查的凭据 | 第一步怎么做 |
|---|---|---|
/v1/apps、应用对话或工作流接口 | 应用的 Service API Key | 从当前应用的 API 或 Secret Key 区域重新复制，不要使用登录密码或控制台会话 Token。 |
/v1/datasets 知识库接口 | 知识库或工作区范围的 Dataset API Key | 确认 Key 属于知识库 API，不能把应用 Key、模型供应商 Key 或控制台 Token 直接替换使用。 |
| 在模型供应商配置页面保存凭据时报 401 | 模型供应商 API Key | 检查该 Key 是否属于当前供应商、区域和端点；这不是 Dify 应用 API Key。 |
/console/api 或登录相关接口 | 控制台会话认证 | 不要套用 Service API 的 Bearer Key；具体认证方式以当前版本 API 文档为准。 |
Dify 官方 API 文档明确要求在 Authorization 请求头中使用 Bearer {API_KEY}，并建议将 API Key 保存在服务端而不是客户端。可先对照Dify API 文档中的认证说明。
最短排查流程：先用最小请求验证 Key
- 确认请求路径。记录你实际请求的是应用、知识库、控制台，还是模型供应商端点。不要只看 Dify 页面上的“API Key”字样。
- 重新复制凭据。从当前应用或知识库的 API 管理区域重新复制；不要手动输入，不要把前后空格、换行或引号一起复制进去。
- 检查请求头。正确形式是
Authorization: Bearer <API_KEY>。常见错误包括漏写Bearer、写成Bearer Bearer xxx、把 Key 放进 URL，或环境变量仍在覆盖新 Key。 - 从服务端发起最小请求。不要先经过浏览器前端、插件或自定义 SDK，这样可以把认证问题与业务参数问题分开。
- 根据响应正文继续定位。401 只说明认证没有被接受；若响应正文已经提示区域、端点、权限或资源不匹配，应按正文处理，而不是继续更换随机 Key。
知识库接口可以用下面的方式做最小验证。请替换为你自己的 Dify 地址、知识库 ID 和知识库 API Key：
curl --request GET \
--url 'https://your-dify-domain/v1/datasets/YOUR_DATASET_ID/documents?page=1&limit=1' \
--header 'Authorization: Bearer YOUR_DATASET_API_KEY'
这个命令只验证请求是否能通过认证和访问该知识库，不代表应用对话接口或模型供应商凭据也有效。路径、认证头和参数形式应以当前Dify API Reference为准。
按报错场景修复 Dify API 401
场景一：请求一开始就返回 invalid api key
优先检查四项：Key 是否属于当前 Dify 实例，Key 是否复制完整，请求头是否只有一个 Bearer，以及请求地址是否指向同一套 Dify 服务。自托管环境中，先在发起请求的机器或容器内打印变量名是否存在，但不要把完整 Key 写入日志：
printf '%s' "$DIFY_API_KEY" | wc -c
长度检查只能发现变量为空或明显截断，不能证明 Key 有效。随后应在服务端使用最小请求验证，并对响应正文做脱敏保存。
场景二：配置模型供应商时返回 401
这时失败的通常不是 Dify 应用 API Key，而是模型供应商插件使用的凭据。检查供应商 API Key、区域和 Base URL 是否配套。官方插件仓库中的一个通义模型案例显示，国内与国际端点的 Key 不能直接混用；该案例还记录了在自托管 Docker 中，相关插件进程运行在 plugin_daemon 容器，因此只修改 api 或 worker 的变量可能不会生效。这个结论只适用于该插件案例，不能泛化到所有模型供应商，应以对应插件文档和错误正文为准。参考官方插件仓库中的端点与 Key 不匹配案例。
场景三：升级或重建容器后，原来的 Key 全部失效
自托管 Dify 需要重点检查 SECRET_KEY 是否持久化，以及 API、worker、worker_beat、plugin_daemon 等服务是否读取了同一配置。Dify 官方仓库的环境示例说明，SECRET_KEY 用于安全签名；官方 API README 也说明可以显式设置该变量，或让 Dify 生成并持久化运行时密钥。
如果问题恰好发生在升级、重建或更换环境之后，先备份当前环境文件和数据库，再核对各容器实际加载的变量。不要为了“试试看”随意生成新 SECRET_KEY，因为改变密钥可能使已有加密数据或令牌无法继续使用。相关背景可查看Dify 官方仓库关于 SECRET_KEY 持久化的 Issue、Dify API README 的 SECRET_KEY 说明以及当前环境变量示例。Issue 中的版本和复现范围不代表所有当前版本，具体是否适用需结合你的部署版本核实。
Docker 自托管的安全核对清单
- 变量来源：区分宿主机的
.env、Compose 文件、平台 Secret 和容器内环境变量，确认新 Key 没有被旧配置覆盖。 - 服务范围：模型插件相关变量要确认实际由哪个插件容器读取；不能看到变量名就假设所有服务都会使用。
- 密钥一致性：需要共享的 Dify 内部密钥必须在相关服务中保持一致；应用 API Key 与模型供应商 Key 则不能混为一谈。
- 重启范围：修改环境变量后，只重启网页容器可能不够；根据变量实际读取服务重启对应容器，并在日志中确认进程已重新加载。
- 日志脱敏：保留 Dify 版本、插件版本、请求路径、状态码、错误正文、request ID 和最后一次配置变更时间，但不要记录完整 API Key。
- 版本边界：Dify 版本、插件版本和界面位置会变化；如果当前页面没有文中所述入口，以当前版本官方文档或本机帮助为准。
不要把 401 和其他错误混在一起
| 状态或现象 | 更适合先查什么 | 是否继续重试 |
|---|---|---|
| 401 invalid api key | Key 类型、Bearer 格式、端点、区域、自托管密钥 | 不建议盲目重试，先修配置 |
| 403 Forbidden | 账号、工作区、应用或知识库权限 | 通常不能靠重试解决 |
| 404 | 域名、路径、版本前缀、资源 ID | 先确认 URL 和资源是否存在 |
| 429 | 限速、并发、额度和 Retry-After | 按响应体和 Retry-After 设计有限重试 |
| 连接超时或断开 | 网络、代理、容器出站连接和服务端状态 | 先区分连接失败与认证失败 |
如果最小请求已经返回 200，但 Dify 页面仍报 401，说明 Key 本身可能有效，问题更可能位于插件调用的另一个端点、环境变量覆盖、缓存配置或插件版本差异。此时应记录实际请求路径和插件日志，而不是继续更换同一类凭据。
常见问题
Dify 的登录密码可以当 API Key 使用吗？
不可以。登录凭据、控制台会话和 Service API Key 属于不同认证上下文。API 请求应使用目标接口要求的 API Key，并按文档放在 Authorization: Bearer 请求头中。
我已经写了 Bearer，为什么仍然是 401？
继续检查是否重复写了 Bearer、Key 是否带有空格或换行、环境变量是否仍是旧值，以及当前 Key 是否属于这个应用或知识库。还要确认请求域名和路径确实指向同一套 Dify 服务。
应用 API Key 能调用知识库接口吗？
不能默认这样认为。应用、知识库和模型供应商可能使用不同范围的凭据。知识库接口应使用该接口要求的知识库 API Key；如果你不确定当前版本的 Key 范围，应以 API Reference 和控制台当前入口为准。
升级后所有 API Key 都失效，应该先重新生成吗？
先不要批量重新生成。先核对自托管实例的 SECRET_KEY 是否被改变、是否持久化，以及相关服务是否加载同一配置。确认配置稳定后，再按最小范围重新生成并替换 Key。
curl 能成功，但 Dify 模型配置仍然报 401，说明什么？
这通常只能说明 curl 验证的端点和凭据可用，不能证明插件使用的端点、区域、请求路径和字段完全相同。请比较两次请求的实际 URL、供应商、区域、插件版本和错误正文，必要时查看插件容器日志。
结论：按这个顺序处理最快
- 先区分应用 API、知识库 API、控制台认证和模型供应商 Key。
- 确认请求头严格使用
Authorization: Bearer <API_KEY>，并排除空格、重复 Bearer 和旧环境变量。 - 用一个最小请求直接验证目标端点，不要先经过前端或复杂插件。
- 如果是模型配置 401，核对供应商、区域和 Base URL；如果是升级后全量失效，检查自托管
SECRET_KEY持久化。 - 保存脱敏后的路径、状态码、响应正文、版本和 request ID，再根据证据决定是否更换 Key 或联系服务维护者。
如果你需要继续处理 OpenAI 兼容接口的 Base URL、模型名或 401 问题，可先参考站内的OpenAI API 401 排查步骤，但不要把其他服务的 Key 规则直接套到 Dify。
常见问题
Dify 的登录密码可以当 API Key 使用吗？
不可以。登录凭据、控制台会话和 Service API Key 属于不同认证上下文，API 请求应使用目标接口要求的 API Key。
已经写了 Bearer，为什么仍然是 401？
检查是否重复写了 Bearer、Key 是否带空格或换行、环境变量是否覆盖了新 Key，以及 Key 是否属于当前应用、知识库或目标服务。
升级后所有 API Key 都失效怎么办？
先核对自托管实例的 SECRET_KEY 是否改变、是否持久化，以及相关服务是否加载同一配置，再决定是否重新生成 Key。
curl 能成功，但 Dify 模型配置仍报 401，说明什么？
curl 只证明所测端点和凭据可用，插件可能调用了不同的端点、区域或请求路径，应比较实际 URL、插件版本和错误正文。
相关阅读
- OpenAI API 401 invalid api key 排查
- Dify 配置 OpenAI 兼容模型 API
- OpenAI 兼容 API Endpoint 怎么填
- OpenAI 兼容 API Key 使用指南
- API 超时分层排查
参考资料
- Dify API 文档：获取知识库的文档列表与 Bearer API Key 认证（docs.dify.ai）
- Dify 官方仓库：API README 与 SECRET_KEY 说明
- Dify 官方仓库：API 环境变量示例
- Dify 官方仓库 Issue：SECRET_KEY 持久化与 API Key 失效案例
- Dify 官方插件仓库 Issue：供应商区域端点与 API Key 不匹配案例