在 n8n 工作流中安全处理 API 密钥、Token 与…

当 n8n 工作流涉及任何认证、API 密钥、Token、OAuth、Bearer、Basic Auth 或密钥值时，通过凭据系统安全引用而非硬编码。

适用场景

解决思路

1. 所有密钥（API 密钥、Bearer Token、OAuth 密钥、密码）必须通过凭据系统传递：使用 newCredential() 或节点的 credentials 参数，绝不要放在文本字段或 SDK 代码里。用 Set 节点硬编码 Token 再通过 {{$json.token}} 读取，本质上仍是明文文本字段。
2. 配置需要认证的节点前，先调用 list_credentials({type}) 列出该类型的凭据。只有一个匹配时，创建时用双参数 newCredential('Label', 'credId') 绑定，或在 update_workflow 上用 setNodeCredential 操作绑定；有多个匹配时，询问用户选择哪一个。单参数 newCredential('Label') 只是占位符，n8n 会自动分配该类型最近编辑的凭据，用户有多个时会静默选错。
3. 凭据创建是用户的工作，不是你的：n8n MCP 不暴露凭据创建接口。告诉用户在 UI 中创建的确切凭据类型，然后在节点配置中按标签引用它。不要尝试以编程方式创建凭据，也不要接受聊天中粘贴的密钥来“稍后设置”。
4. 优先使用原生凭据：每个原生节点（Slack、Gmail、Postgres、OpenAI 等）都有对应的凭据类型。存在原生选项时不要退而使用通用凭据类型。
5. 对于多请求头或“请求头加查询参数”的认证形式，使用 httpCustomAuth 凭据类型（参见 references/CUSTOM_CREDENTIALS.md）。
6. 理解凭据系统模型：凭据是 n8n 中的一等对象，静态加密存储在数据库中，由需要它们的节点按 ID 引用，作用域为项目（Cloud 和企业版）或全局共享（部分自托管），由类型 slug 标识（如 googleSheetsOAuth2Api、slackApi、httpHeaderAuth）。需要认证的节点有 credentials 参数指向凭据 ID 加类型，密钥值从不出现在工作流 JSON 中，导出工作流只泄露引用而非密钥。
7. 按决策树选择认证方式：若存在原生凭据（Slack、Gmail、OpenAI、Postgres 等），直接用原生节点及其凭据类型；若服务是“标准形状”（REST + Bearer/Basic/OAuth），用 HTTP Request 配合内置认证类型之一（Generic OAuth2、Header Auth、Bearer Auth、Basic Auth、Custom Auth，参见 references/HTTP_REQUEST_WITH_AUTH.md）；若服务需要多个静态请求头，或请求头加查询参数，使用 httpCustomAuth 凭据类型（参见 references/CUSTOM_CREDENTIALS.md）。
8. 当用户把密钥粘贴到聊天中时：第一，不要把 Token 放进文本字段，哪怕临时也不行（Set 节点硬编码再通过 {{$json.token}} 引用仍是明文文本字段）；第二，尽量绑定到已有凭据，先 list_credentials({type})，有匹配就用 setNodeCredential 绑定并告知用户用了哪个，没有就告诉用户在 UI 中创建（Bearer Token 用 Bearer Auth，自定义请求头用 Header Auth 等），凭据创建仍仅限 UI；第三，把粘贴的密钥视为已泄露，明确告诉用户轮换它，不要淡化——Token 已传输给 LLM 提供商，可能残留在聊天历史、转录和缓存层中，应告知：“新凭据设置好后立即轮换此 Token，把它当作已泄露处理。”
9. 当没有原生节点时：使用 HTTP Request 配合适当的认证。参考 references/FINDING_API_DOCS.md 发现认证方案、基础 URL 和常见形状；references/HTTP_REQUEST_WITH_AUTH.md 将 HTTP Request 接入凭据；references/CUSTOM_CREDENTIALS.md 处理内置认证类型不适用的情况。
10. 按需查阅参考文件：需要理解凭据如何存储、引用、作用域或轮换时读 references/CREDENTIAL_SYSTEM.md；需要在一个凭据中处理多请求头/请求头加查询参数认证，或按请求签名模式（HMAC、JWT、Webhook 验证）时读 references/CUSTOM_CREDENTIALS.md；配置 HTTP Request 认证（Bearer、Basic、OAuth、Header Auth）时读 references/HTTP_REQUEST_WITH_AUTH.md；用户提到你不具备节点级知识的服务时读 references/FINDING_API_DOCS.md。
11. 避免反模式：不要把 sk-... 粘贴到 HTTP Request 的 Authorization 请求头值字段（Token 明文出现在工作流 JSON 中，导出、复制、截图都会泄露），应使用凭据（Bearer Token 用 Bearer Auth，其他自定义认证方案用 Header Auth）；不要把 Token 存在 Set 节点再用表达式引用（同样问题，值存在于工作流 JSON 中），同样改用凭据；不要把密钥存在 $vars.X 中并作为认证值读取（静态不加密、导出泄露、无法轮换），应使用正确的凭据类型（httpBearerAuth、httpHeaderAuth、httpCustomAuth 或原生类型），入站 Webhook 认证应使用触发器的 authentication 字段，而不是对 $vars.token 做 IF 判断；不要在自定义认证设置中用 $env.X 读取密钥（不工作，运行时抛错），应使用适当类型的凭据；存在原生节点时不要用 HTTP Request（会失去 OAuth 自动刷新、原生错误处理，代码更多），应使用原生节点；不要在 SDK 代码中硬编码凭据（如 new HttpRequest({ headers: { Authorization: 'Bearer xxx' } })），同样会泄露，应在 SDK 代码中使用 newCredential()；不要让用户创建凭据却不指明凭据类型（用户会选错类型，认证失败且难以排查），始终明确说明：“创建一个类型为 <确切类型名> 的凭据”。

适用边界 · 注意事项

• n8n MCP 不暴露凭据创建接口，无法以编程方式创建凭据，必须由用户在 UI 中完成。
• 不要接受用户在聊天中粘贴的密钥来“稍后设置”，应视为已泄露并让用户轮换。
• 存在原生节点/凭据时不要退而使用通用 HTTP Request 或通用凭据类型。