API Authentication

Learn how to authenticate your API requests using API keys and manage access scopes

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:

1. Navigate to Settings

   Go to Settings → API in your n8n instance.

2. Create New Key

   Click Create API Key and provide:

   • A descriptive label
   • Selected scopes (permissions)
   • Optional expiration date
3. 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

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

JavaScript (fetch)

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();

Python (requests)

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()

Node.js (axios)

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

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

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

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

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

const response = await fetch('https://your-n8n-instance.com/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'X-N8N-API-KEY': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    label: 'Integration API Key',
    scopes: ['workflow:read', 'execution:read'],
    expiresAt: null
  })
});

const newKey = await response.json();
console.log('Save this key:', newKey.rawApiKey);

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

id · string · required

The API key ID

label · string

New label for the API key

scopes · string[]

Updated array of permission scopes

cURL

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

id · string · required

The API key ID to delete

cURL

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