Authentication

n8n uses API keys to authenticate API calls.

Feature availability

The n8n API isn't available during the free trial. Please upgrade to access this feature.

Create an API key

1. Log in to n8n.

2. Go to Settings > n8n API.

3. Select Create an API key.

4. Choose a Label and set an Expiration time for the key.

5. If on an Enterprise plan, choose the Scopes to give the key. Refer to API Scopes for the full list of available scopes.

6. Copy My API Key and use this key to authenticate your calls.

Call the API using your key

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

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

# For a self-hosted n8n instance <a href="#for-a-self-hosted-n8n-instance" id="for-a-self-hosted-n8n-instance"></a>
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 <a href="#for-n8n-cloud" id="for-n8n-cloud"></a>
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

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

• API Key: paste the key you created in Create an API key.

• Base URL: enter your instance's API root in one of these formats:

  • Cloud: https://<name>.app.n8n.cloud/api/v1, where <name> is your Cloud subdomain.

  • Self-hosted: https://<your-instance-url>/api/v1.

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

Delete an API key

1. Log in to n8n.

2. Go to Settings > n8n API.

3. Select Delete next to the key you want to delete.

4. Confirm the delete by selecting Delete Forever.

API Scopes

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.

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

API key scopes vs. project role scopes

API key scopes control what an API key can do at the instance level. They differ from the project role scopes used to define custom roles inside a project. For project role scopes, refer to Custom project roles.

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

Community package scopes

Scope	Description
communityPackage:install	Install a community node package on the instance.
communityPackage:list	List installed community node packages.
communityPackage:uninstall	Uninstall a community node package.
communityPackage:update	Update an installed community node package.

Credential scopes

Scope	Description
credential:create	Create credentials.
credential:read	Retrieve a credential and its data schema.
credential:list	List credentials.
credential:update	Update a credential.
credential:delete	Delete a credential.
credential:move	Transfer a credential to another project.

Data table scopes

Scope	Description
dataTable:create	Create a data table.
dataTable:read	Retrieve a data table.
dataTable:list	List data tables.
dataTable:update	Update a data table's metadata.
dataTable:delete	Delete a data table.

Data table column scopes

Scope	Description
dataTableColumn:create	Add a column to a data table.
dataTableColumn:read	Retrieve a data table column.
dataTableColumn:update	Update a data table column.
dataTableColumn:delete	Delete a data table column.

Data table row scopes

Scope	Description
dataTableRow:create	Insert rows into a data table.
dataTableRow:read	Read rows from a data table.
dataTableRow:update	Update existing rows in a data table.
dataTableRow:delete	Delete rows from a data table.
dataTableRow:upsert	Update an existing row in a data table, or insert a new one if no row matches the filter conditions.

Execution scopes

Scope	Description
execution:read	Retrieve an execution and its details.
execution:list	List executions.
execution:retry	Retry a failed execution.
execution:stop	Stop a running execution.
execution:delete	Delete an execution.

Execution tags scopes

Scope	Description
executionTags:list	Read the annotation tags assigned to an execution.
executionTags:update	Update the annotation tags assigned to an execution.

Folder scopes

Scope	Description
folder:create	Create a folder in a project.
folder:read	Retrieve a folder.
folder:list	List folders in a project.
folder:update	Update a folder.
folder:delete	Delete a folder.

Insights scopes

Scope	Description
insights:read	Read instance insights data, including execution counts, failure rates, time saved, and average run time.

Project scopes

Scope	Description
project:create	Create a project.
project:list	List projects.
project:update	Update a project.
project:delete	Delete a project.

Security audit scopes

Scope	Description
securityAudit:generate	Generate a security audit report for the instance.

Source control scopes

Scope	Description
sourceControl:pull	Pull changes from the connected source control repository into the instance.

Tag scopes

Scope	Description
tag:create	Create a tag in the global tag registry.
tag:read	Retrieve a tag.
tag:list	List tags.
tag:update	Update a tag.
tag:delete	Delete a tag.

User scopes

Scope	Description
user:create	Invite or create users on the instance.
user:read	Retrieve a user.
user:list	List users.
user:changeRole	Change a user's global (instance-level) role.
user:enforceMfa	Reserved scope. No /api/v1/ endpoint consumes it, so selecting this scope on a Public API key has no public-facing effect.
user:delete	Delete a user from the instance.

Variable scopes

Scope	Description
variable:create	Create an instance variable.
variable:list	List instance variables.
variable:update	Update an instance variable.
variable:delete	Delete an instance variable.

Workflow scopes

Scope	Description
workflow:create	Create a workflow.
workflow:read	Retrieve a workflow and its details.
workflow:list	List workflows.
workflow:update	Update a workflow.
workflow:delete	Delete, archive, or unarchive a workflow.
workflow:move	Transfer a workflow to another project.
workflow:activate	Activate or deactivate a workflow. Also referred to as "publish/unpublish" in the public API (/workflows/{id}/activate and /workflows/{id}/deactivate).

Workflow tags scopes

Scope	Description
workflowTags:list	Read the tags assigned to a workflow.
workflowTags:update	Update the tags assigned to a workflow.