Skip to content

API 身份验证(API authentication)#

n8n 使用 API 密钥对 API 调用进行身份验证。

🌐 n8n uses API keys to authenticate API calls.

功能可用性

在免费试用期间，n8n API 无法使用。请升级以访问此功能。

创建 API 密钥(Create an API key)#

  1. 登录到 n8n
  2. 转到 设置 > n8n API。
  3. 选择 创建 API 密钥。
  4. 选择一个标签并为密钥设置到期时间。
  5. 如果使用企业计划，请选择要赋予密钥的 Scopes。完整可用范围列表请参阅 API Scopes。
  6. 复制 我的 API 密钥 并使用此密钥来验证你的调用。

使用你的密钥调用 API(Call the API using your key)#

在你的 API 调用中，将 API 密钥作为名为 X-N8N-API-KEY 的请求头发送。

🌐 Send the API key in your API call as a header named X-N8N-API-KEY.

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

🌐 For example, say you want to get all active workflows. Your curl request will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# For a self-hosted n8n instance
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>'

# For 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>'

节点配置(Node configuration)#

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

🌐 To call the n8n API from within a workflow, use the n8n node. When you create the credential, fill these fields:

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

有关可用的操作和参数，请参阅 n8n 节点 文档。

🌐 For the available operations and parameters, refer to the n8n node documentation.

删除 API 密钥(Delete an API key)#

  1. 登录到 n8n
  2. 转到 设置 > n8n API。
  3. 选择要删除密钥旁边的删除。
  4. 通过选择 永久删除 来确认删除。

API 作用域(API Scopes)#

企业实例 的用户可以通过作用域限制 API 密钥可以访问的资源和操作。请选择密钥预期用途所需的最小作用域。

🌐 Users of enterprise instances can limit which resources and actions an API key can access with scopes. Choose the minimum scopes needed for the key's intended purpose.

非企业级 API 密钥拥有对账户所有资源和功能的完全访问权限。

🌐 Non-enterprise API keys have full access to all the account's resources and capabilities.

API 密钥作用域 vs. 项目角色作用域

API 密钥作用域控制 API 密钥在实例级别可以执行的操作。它们与用于在项目内定义自定义角色的 项目角色作用域 不同。有关项目角色作用域，请参阅 自定义项目角色。

以下表格列出了创建作用域 API 密钥时可用的作用域，按资源分组。

🌐 The following tables list the scopes available when you create a scoped API key, grouped by resource.

社区软件包范围(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 更新数据表的元数据。
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/ 端点使用它，因此在公共 API 密钥上选择此范围不会产生面向公众的效果。
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 激活或停用工作流。在公共 API 中也称为“发布/取消发布” (/workflows/{id}/activate 和 /workflows/{id}/deactivate)。

工作流标签范围(Workflow tags scopes)#

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