n8n 登录与鉴权：API 密钥获取及配置方法

星野 技术创作者 2026-11-01 10 阅读

n8n 的网页登录负责进入编辑器，API 密钥负责让脚本、命令行或第三方工具调用实例；2026 年 10 月 20 日更新的官方鉴权文档重新明确了密钥创建入口和请求头格式，现在值得按这条路径配置，避免把登录密码、节点凭据和 API 密钥混为一谈。

先分清三种“登录”

n8n 中至少有三种容易混淆的凭据：

类型 用途 创建或填写位置
网页账号 登录 n8n，进入工作流编辑器 登录页或云端实例入口
节点凭据 让 OpenAI、数据库等节点访问外部服务 节点的 Credentials 设置
n8n API 密钥 调 n8n 自己的 REST API Settings → n8n API

本文处理的是第三种：获取 n8n API 密钥，并放进正确的 HTTP 请求头。节点凭据虽然也叫“密钥”，但它通常只服务某个节点；它不能替代 n8n API 密钥。

n8n 官方首页把自身分为 Cloud 与自托管两种使用方式，并明确提供 Docker 自托管路径 —— 这决定了你的 API 密钥是挂在 n8n Cloud 账号下，还是挂在自己服务器的实例里，两者的密钥互不通用。

开始前准备这 3 项

  1. 准备可登录的 n8n 实例：云端用户打开 n8n 官网，点击页面右上角 Sign in；自托管用户打开自己的实例地址，确认能进入编辑器。判断标准是页面顶部能看到工作流编辑器，而不是停留在登录表单。
  2. 确认实例地址与 Base URL 口径：按官方 Authentication 文档，n8n 节点凭据里的 Base URL 要填实例根地址 + /api/v1 —— Cloud 是 https://<your-name>.app.n8n.cloud/api/v1，自托管是 https://<your-instance-url>/api/v1。两个常见错法：只填根地址（少 /api/v1）或把它拼两遍；写脚本手拼完整 URL 时同理（见下文示例）。
  3. 准备 API 调用环境：自托管可用 Docker；官方仓库给出的快速安装命令需要 Docker。云端则直接使用浏览器控制台或本机 curl。需要填密钥的第三方工具，还要支持自定义 HTTP 请求头。

在 n8n 中创建 API 密钥

  1. 登录目标 n8n 实例，确认当前进入的是准备被调用的那个工作区。
  2. 打开左下角的个人菜单或设置入口，进入：
Settings → n8n API
  1. 点击 Create an API key。
  2. 填写 Label，用能区分用途的名称，例如 local-cli 或 automation-agent。
  3. 设置 Expiration time，避免创建长期有效的共享密钥。
  4. 如果当前是 Enterprise 计划，在 Scopes 中限定密钥权限；非 Enterprise 密钥不能按资源范围收窄，因此不要把它复制到个人电脑或不熟悉的脚本环境中。
  5. 点击创建后，在 My API Key 旁复制密钥。API 密钥属于私密凭据，不要写进 Git 仓库、截图、聊天记录或工作流节点参数。

官方文档给出的路径和字段名称可以原样照做：

Log in to n8n
→ Settings → n8n API
→ Create an API key
→ Label
→ Expiration time
→ Scopes（仅 Enterprise）
→ Copy My API Key

Enterprise 用户配置 Scopes 时，应继续查看官方文档中的 API Scopes 页面，逐项选择工作流实际需要的权限，而不是直接复制示例命令中的所有能力。

把密钥放进正确的请求头

n8n API 不接受用户名和密码组合。官方鉴权文档明确要求把创建的密钥放入名为 X-N8N-API-KEY 的请求头。

下面这段命令可直接复制后替换实例地址、端口、路径、版本号和密钥：

curl -X 'GET' 
  '<N8N_HOST>:<N8N_PORT>/<N8N_PATH>/api/v<version-number>/workflows?active=true' 
  -H 'accept: application/json' 
  -H 'X-N8N-API-KEY: <your-api-key>'

自托管实例的地址必须包含实际协议、主机名、端口和 n8n 路径。例如，n8n 若运行在 https://workflow.example.com 且没有额外路径，请求地址应是：

https://workflow.example.com/api/v1/workflows?active=true

如果部署在 https://workflow.example.com/n8n/，则应改成：

https://workflow.example.com/n8n/api/v1/workflows?active=true

不要只因为请求成功返回 JSON 就认为鉴权没问题：还应检查返回的 workflows 是否属于当前实例。向错误地址发送有效密钥，可能返回鉴权成功，却连接到另一套工作区。创建时填写的 Label 只能帮助人识别密钥，不能替代请求头名称；真正的机器鉴权依据仍然是 X-N8N-API-KEY。

在工作流节点中复用密钥

如果还要从 n8n 工作流内部调用另一个 n8n 实例或自身 API，应使用 n8n 节点，而不是普通 HTTP Request 节点。官方文档给出的节点配置方式是：

  1. 新建 n8n 节点。
  2. 打开节点的 Credential 配置。
  3. 在 API Key 字段粘贴刚创建的密钥。
  4. 填写目标实例地址及所需 API 路径，保存后执行一次测试。
场景 放置位置 验证方式
curl、脚本调用 X-N8N-API-KEY 请求头 请求返回当前实例的活动工作流
n8n 节点调用 n8n API 节点的 API Key 凭据字段 节点测试成功并返回目标实例数据
OpenAI、数据库等节点 对应节点的 Credentials 节点自身测试成功

后两种“节点测试成功”不能互相替代。一个节点连接成功，不代表另一个 n8n 实例的密钥配置正确。

会卡住的两个地方

密钥放错位置

官方文档规定的请求头名称是 X-N8N-API-KEY，而不是 Authorization、Api-Key 或节点凭据名称。排查时先对照这一个字段；不要同时在多个请求头中放同一密钥，以免掩盖到底是哪一项生效。

另外，URL 中只能放实例地址和 API 路径，不要写成：

https://workflow.example.com/api/v1?X-N8N-API-KEY=密钥

官方示例明确把密钥放在请求头中，查询参数位置不是它认可的位置。

登录状态与 API 鉴权不是一回事

浏览器里点 Sign in 之后的网页登录会话，只对网页界面有效；脚本和工作流节点走 API 用的是另一套凭据 —— 每次请求都要带 X-N8N-API-KEY 请求头。两者互相独立：网页会话过期重登，不会让密钥失效；密钥被删了，网页照样登得进去。所以”网页能打开但接口 401″时，先看密钥，别去反复重登网页。

怎么确认已经配好

按下面三个可观察结果验收：

  1. Settings → n8n API 页面能看到刚创建的密钥记录，Label 和过期时间与预期一致。
  2. 复制上面的 curl 示例后，请求没有因缺少鉴权信息而失败，并且返回的数据属于目标实例。
  3. 在 n8n 节点里使用时，节点测试能够取得目标实例的数据，而不是只显示“Credentials saved”。

如果第 1 步成功、第 2 步失败，优先检查请求头拼写、Base URL 路径和密钥是否复制完整；如果第 2 步成功、第 3 步失败，则检查 n8n 节点的 API Key 字段与目标地址。完整鉴权示例见 n8n 官方 Authentication 文档，自托管部署和仓库内容见 n8n 官方 GitHub 仓库，云端入口与产品功能见 n8n 官网。

参考来源

# AI# 知识

评论区

0 条评论

登录后可评论。

星野 10 阅读