API Authentication

Overview

n8n uses API key authentication to secure its REST API. Each API key can be configured with specific scopes to control access to different resources and operations.

Creating an API Key

You can create API keys through the n8n user interface:

Navigate to Settings

Go to Settings → API in your n8n instance.

Create New Key

Click Create API Key and provide:

A descriptive label
Selected scopes (permissions)
Optional expiration date

Save the Key

Copy the generated API key immediately. It won’t be shown again for security reasons.

API keys are sensitive credentials. Store them securely and never commit them to version control.

Authentication Methods

API Key Header (Recommended)

Pass your API key in the X-N8N-API-KEY header:

curl -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/workflows

cURL
JavaScript (fetch)
Python (requests)
Node.js (axios)

curl -X GET \
  -H "X-N8N-API-KEY: n8n_api_1234567890abcdef" \
  -H "Content-Type: application/json" \
  https://your-n8n-instance.com/api/v1/workflows

const response = await fetch('https://your-n8n-instance.com/api/v1/workflows', {
  headers: {
    'X-N8N-API-KEY': 'n8n_api_1234567890abcdef',
    'Content-Type': 'application/json'
  }
});

const workflows = await response.json();

import requests

headers = {
    'X-N8N-API-KEY': 'n8n_api_1234567890abcdef',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://your-n8n-instance.com/api/v1/workflows',
    headers=headers
)

workflows = response.json()

const axios = require('axios');

const response = await axios.get('https://your-n8n-instance.com/api/v1/workflows', {
  headers: {
    'X-N8N-API-KEY': 'n8n_api_1234567890abcdef',
    'Content-Type': 'application/json'
  }
});

const workflows = response.data;

Managing API Keys

List API Keys

Retrieve all API keys for your account.

GET /api/v1/api-keys

curl -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/api-keys

Response:

[
  {
    "id": "key_123",
    "label": "Production API Key",
    "apiKey": "n8n_api_••••••••••••cdef",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": null,
    "scopes": ["workflow:read", "workflow:execute"]
  }
]

API keys in list responses are redacted for security. Only the first few and last few characters are visible.

Create API Key

Generate a new API key with specified permissions.

POST /api/v1/api-keys

label

string

required

A descriptive name for the API key

scopes

string[]

required

Array of permission scopes for this key

expiresAt

number

default:"null"

Unix timestamp (seconds) when the key expires. null for no expiration.

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Integration API Key",
    "scopes": ["workflow:read", "execution:read"],
    "expiresAt": null
  }' \
  https://your-n8n-instance.com/api/v1/api-keys

Response:

{
  "id": "key_456",
  "label": "Integration API Key",
  "apiKey": "n8n_api_••••••••••••cdef",
  "rawApiKey": "n8n_api_1234567890abcdef1234567890abcdef",
  "createdAt": "2024-02-19T14:20:00.000Z",
  "updatedAt": "2024-02-19T14:20:00.000Z",
  "expiresAt": null,
  "scopes": ["workflow:read", "execution:read"]
}

The rawApiKey field is only returned on creation. Store it securely as it cannot be retrieved again.

Update API Key

Modify an existing API key’s label or scopes.

PATCH /api/v1/api-keys/:id

string

required

The API key ID

label

string

New label for the API key

scopes

string[]

Updated array of permission scopes

curl -X PATCH \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Updated API Key",
    "scopes": ["workflow:read", "workflow:update"]
  }' \
  https://your-n8n-instance.com/api/v1/api-keys/key_456

Response:

{
  "success": true
}

Delete API Key

Revoke an API key permanently.

DELETE /api/v1/api-keys/:id

string

required

The API key ID to delete

curl -X DELETE \
  -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/api-keys/key_456

Response:

{
  "success": true
}

Get Available Scopes

Retrieve the list of scopes available for your user role.

GET /api/v1/api-keys/scopes

Response:

[
  "workflow:read",
  "workflow:create",
  "workflow:update",
  "workflow:delete",
  "workflow:execute",
  "credential:read",
  "credential:create",
  "credential:update",
  "credential:delete",
  "execution:read",
  "execution:list"
]

API Key Scopes

Workflow Scopes

workflow:read

scope

Read workflow configurations and metadata

workflow:create

scope

Create new workflows

workflow:update

scope

Modify existing workflows

workflow:delete

scope

Delete workflows

workflow:execute

scope

Trigger workflow executions

workflow:list

scope

List all accessible workflows

workflow:activate

scope

Activate workflows to run automatically

workflow:deactivate

scope

Deactivate active workflows

Credential Scopes

credential:read

scope

Read credential metadata (not sensitive data)

credential:create

scope

Create new credentials

credential:update

scope

Update existing credentials

credential:delete

scope

Delete credentials

credential:list

scope

List all accessible credentials

Execution Scopes

execution:read

scope

Read execution data and results

execution:list

scope

List workflow executions

execution:retry

scope

Retry failed executions

execution:stop

scope

Stop running executions

execution:delete

scope

Delete execution records

Security Best Practices

Rotate Keys Regularly

Generate new API keys periodically and revoke old ones to minimize security risks.

Use Minimum Required Scopes

Only grant the scopes necessary for your integration. This limits potential damage if a key is compromised.

Set Expiration Dates

For temporary integrations or testing, set an expiration date on API keys.

Monitor API Usage

Regularly review your API keys and their usage patterns to detect unauthorized access.

Use Environment Variables

Store API keys in environment variables, never hardcode them in your application.

export N8N_API_KEY="your-api-key"

Implement Request Signing (Advanced)

For high-security scenarios, consider implementing request signing or using OAuth where available.

License Requirements

API Key Scopes is an enterprise feature. Without a license, API keys have access to all available scopes for the user’s role.

Common Issues

401 Unauthorized

Problem: Request returns 401 Unauthorized Solutions:

Verify the API key is correct
Check that the key hasn’t expired
Ensure you’re using the correct header name: X-N8N-API-KEY

403 Forbidden

Problem: Request returns 403 Forbidden Solutions:

Verify your API key has the required scope for the operation
Check that the key is active and not revoked
Ensure you have access to the requested resource

Rate Limiting

Problem: Request returns 429 Too Many Requests Solutions:

Implement exponential backoff
Reduce request frequency
Cache responses when possible
Contact support for higher limits if needed

Next Steps

Workflows API

Start managing workflows programmatically

Executions API

Monitor and control workflow executions

Credentials API

Manage authentication credentials

API Overview

Return to API overview

Core API

Node API

API Authentication

Overview

Creating an API Key

Authentication Methods

API Key Header (Recommended)

Managing API Keys

List API Keys

Create API Key

Update API Key

Delete API Key

Get Available Scopes

API Key Scopes

Workflow Scopes

Credential Scopes

Execution Scopes

Security Best Practices

License Requirements

Common Issues

401 Unauthorized

403 Forbidden

Rate Limiting

Next Steps

Workflows API

Executions API

Credentials API

API Overview

Core API

Node API

​Overview

​Creating an API Key

​Authentication Methods

​API Key Header (Recommended)

​Managing API Keys

​List API Keys

​Create API Key

​Update API Key

​Delete API Key

​Get Available Scopes

​API Key Scopes

​Workflow Scopes

​Credential Scopes

​Execution Scopes

​Security Best Practices

​License Requirements

​Common Issues

​401 Unauthorized

​403 Forbidden

​Rate Limiting

​Next Steps

Workflows API

Executions API

Credentials API

API Overview

Overview

Creating an API Key

Authentication Methods

API Key Header (Recommended)

Managing API Keys

List API Keys

Create API Key

Update API Key

Delete API Key

Get Available Scopes

API Key Scopes

Workflow Scopes

Credential Scopes

Execution Scopes

Security Best Practices

License Requirements

Common Issues

401 Unauthorized

403 Forbidden

Rate Limiting

Next Steps