API 身份验证#

n8n 使用 API 密钥来验证 API 调用。

功能可用性

n8n API 在免费试用期间不可用。请升级以访问此功能。

创建 API 密钥#

登录 n8n。
转到 Settings 设置 > n8n API。
选择 Create an API key 创建 API 密钥。
为密钥选择 Label 标签并设置 Expiration 过期时间。
如果使用 Enterprise 计划，请选择要授予密钥的 Scopes 范围。可用范围的完整列表请参阅 API Scopes API 范围。
复制 My API Key 我的 API 密钥，并使用此密钥对调用进行身份验证。

使用您的密钥调用 API#

在您的 API 调用中发送 API 密钥作为名为 X-N8N-API-KEY 的标头。

例如，假设您想要获取所有活动工作流。您的 curl 请求将如下所示：

# 对于自托管的 n8n 实例
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 Cloud
curl -X 'GET' \
  '<your-cloud-instance>/api/v<version-number>/workflows?active=true' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'

节点配置#

要从工作流中调用 n8n API，请使用 n8n 节点。创建凭据时，填写以下字段：

API Key：粘贴你创建的密钥。
Base URL：使用以下格式之一输入实例的 API 根地址：
- Cloud：https://<name>.app.n8n.cloud/api/v1，其中 <name> 是你的 Cloud 子域名。
- 自托管：https://<your-instance-url>/api/v1。

可用操作和参数请参阅 n8n 节点文档。

删除 API 密钥#

登录 n8n。
转到 Settings 设置 > n8n API。
在要删除的密钥旁边选择 Delete 删除。
选择 Delete Forever 永久删除确认删除。

API Scopes API 范围#

Enterprise 实例的用户可以使用范围限制 API 密钥可访问的资源和操作。请为密钥的预期用途选择所需的最小范围。

非 Enterprise API 密钥对账户的所有资源和功能具有完全访问权限。

API key scopes 与 project role scopes

API key scopes 控制 API 密钥在实例级别可以执行的操作。它们不同于用于在项目内定义自定义角色的 project role scopes 项目角色范围。项目角色范围请参阅自定义项目角色。

下表按资源列出创建限定范围 API 密钥时可用的范围。

Community package scopes 社区包范围#

范围	说明
`communityPackage:install`	在实例上安装社区节点包。
`communityPackage:list`	列出已安装的社区节点包。
`communityPackage:uninstall`	卸载社区节点包。
`communityPackage:update`	更新已安装的社区节点包。

Credential scopes 凭据范围#

范围	说明
`credential:create`	创建凭据。
`credential:read`	检索凭据及其数据架构。
`credential:list`	列出凭据。
`credential:update`	更新凭据。
`credential:delete`	删除凭据。
`credential:move`	将凭据转移到另一个项目。

Data table scopes 数据表范围#

范围	说明
`dataTable:create`	创建数据表。
`dataTable:read`	检索数据表。
`dataTable:list`	列出数据表。
`dataTable:update`	更新数据表的 metadata。
`dataTable:delete`	删除数据表。

Data table column scopes 数据表列范围#

范围	说明
`dataTableColumn:create`	向数据表添加列。
`dataTableColumn:read`	检索数据表列。
`dataTableColumn:update`	更新数据表列。
`dataTableColumn:delete`	删除数据表列。

Data table row scopes 数据表行范围#

范围	说明
`dataTableRow:create`	向数据表插入行。
`dataTableRow:read`	读取数据表中的行。
`dataTableRow:update`	更新数据表中的现有行。
`dataTableRow:delete`	删除数据表中的行。
`dataTableRow:upsert`	更新数据表中的现有行；如果没有行匹配筛选条件，则插入新行。

Execution scopes 执行范围#

范围	说明
`execution:read`	检索执行及其详情。
`execution:list`	列出执行。
`execution:retry`	重试失败的执行。
`execution:stop`	停止正在运行的执行。
`execution:delete`	删除执行。

Execution tags scopes 执行标签范围#

范围	说明
`executionTags:list`	读取分配给执行的注释标签。
`executionTags:update`	更新分配给执行的注释标签。

Folder scopes 文件夹范围#

范围	说明
`folder:create`	在项目中创建文件夹。
`folder:read`	检索文件夹。
`folder:list`	列出项目中的文件夹。
`folder:update`	更新文件夹。
`folder:delete`	删除文件夹。

Insights scopes 洞察范围#

范围	说明
`insights:read`	读取实例洞察数据，包括执行次数、失败率、节省时间和平均运行时间。

Project scopes 项目范围#

范围	说明
`project:create`	创建项目。
`project:list`	列出项目。
`project:update`	更新项目。
`project:delete`	删除项目。

Security audit scopes 安全审计范围#

范围	说明
`securityAudit:generate`	为实例生成安全审计报告。

Source control scopes 源代码控制范围#

范围	说明
`sourceControl:pull`	从已连接的源代码控制仓库拉取更改到实例中。

Tag scopes 标签范围#

范围	说明
`tag:create`	在全局标签注册表中创建标签。
`tag:read`	检索标签。
`tag:list`	列出标签。
`tag:update`	更新标签。
`tag:delete`	删除标签。

User scopes 用户范围#

范围	说明
`user:create`	在实例上邀请或创建用户。
`user:read`	检索用户。
`user:list`	列出用户。
`user:changeRole`	更改用户的全局（实例级）角色。
`user:enforceMfa`	保留范围。没有 `/api/v1/` 端点会使用它，因此在 Public API 密钥上选择此范围不会产生面向 public 的效果。
`user:delete`	从实例中删除用户。

Variable scopes 变量范围#

范围	说明
`variable:create`	创建实例变量。
`variable:list`	列出实例变量。
`variable:update`	更新实例变量。
`variable:delete`	删除实例变量。

Workflow scopes 工作流范围#

范围	说明
`workflow:create`	创建工作流。
`workflow:read`	检索工作流及其详情。
`workflow:list`	列出工作流。
`workflow:update`	更新工作流。
`workflow:delete`	删除、归档或取消归档工作流。
`workflow:move`	将工作流转移到另一个项目。
`workflow:activate`	激活或停用工作流。在 Public API 中也称为 "publish/unpublish"（`/workflows/{id}/activate` 和 `/workflows/{id}/deactivate`）。

Workflow tags scopes 工作流标签范围#

范围	说明
`workflowTags:list`	读取分配给工作流的标签。
`workflowTags:update`	更新分配给工作流的标签。