# 02-AUTHENTICATION.md - n8n REST API Authentication
**Версия API:** v1
**Дата документации:** 2025-12-25
**Источник:** Официальная документация n8n через Context7
---
## 📋 Содержание
1. [Введение](#введение)
2. [Метод аутентификации](#метод-аутентификации)
3. [Создание API ключа](#создание-api-ключа)
4. [Использование API ключа](#использование-api-ключа)
5. [Примеры запросов](#примеры-запросов)
6. [Безопасность](#безопасность)
7. [Troubleshooting](#troubleshooting)
8. [Best Practices](#best-practices)
---
## Введение
Все запросы к n8n REST API требуют аутентификации. n8n использует **API key authentication** через HTTP header для обеспечения безопасного доступа к вашим workflows, executions, credentials и другим ресурсам.
**Важно:** API ключи предоставляют полный доступ к вашему n8n instance. Храните их в безопасности и никогда не делитесь ими публично.
---
## Метод аутентификации
### API Key Authentication
n8n REST API использует **API key authentication** с использованием HTTP header:
```http
X-N8N-API-KEY: your_api_key_here
```
**Характеристики:**
- ✅ Простая в использовании
- ✅ Безопасная при использовании HTTPS
- ✅ Поддерживается всеми HTTP клиентами
- ✅ Не требует OAuth flow
- ✅ Ideal для server-to-server интеграций
**Формат:**
```http
X-N8N-API-KEY: <your-api-key>
```
**Где:**
- `<your-api-key>` - ваш уникальный API ключ, сгенерированный в n8n
---
## Создание API ключа
### n8n Cloud
**Шаг 1:** Войдите в ваш n8n Cloud instance
```
https://your-instance.app.n8n.cloud
```
**Шаг 2:** Перейдите в Settings
- Кликните на иконку пользователя в правом верхнем углу
- Выберите **Settings**
**Шаг 3:** Найдите раздел API
- В меню Settings найдите раздел **API**
- Кликните на **API**
**Шаг 4:** Создайте новый API ключ
- Кликните на кнопку **Create API Key**
- (Опционально) Введите описание для ключа (например, "Production Integration", "CI/CD Pipeline")
- Кликните **Create**
**Шаг 5:** Скопируйте и сохраните ключ
- API ключ отобразится **только один раз**
- Скопируйте ключ и сохраните в безопасном месте
- После закрытия окна ключ больше не будет доступен для просмотра
**⚠️ Важно:** Вы не сможете просмотреть ключ снова после создания. Если потеряете ключ, создайте новый и удалите старый.
### Self-Hosted n8n
**Шаг 1:** Войдите в ваш self-hosted n8n instance
```
https://n8n.example.com
```
или
```
http://localhost:5678
```
**Шаг 2-5:** Повторите те же шаги, что и для n8n Cloud
**Дополнительные настройки (Self-Hosted):**
Вы можете отключить Public API через environment variable:
```bash
export N8N_PUBLIC_API_DISABLED=true
```
Отключить API Playground (Swagger UI):
```bash
export N8N_PUBLIC_API_SWAGGERUI_DISABLED=true
```
---
## Использование API ключа
### HTTP Header
API ключ передается через HTTP header `X-N8N-API-KEY` в каждом запросе:
```http
GET /api/v1/workflows HTTP/1.1
Host: your-instance.app.n8n.cloud
X-N8N-API-KEY: your_api_key_here
Accept: application/json
```
### Обязательные Headers
Каждый API запрос должен включать:
1. **X-N8N-API-KEY** (Required) - Ваш API ключ
```http
X-N8N-API-KEY: your_api_key_here
```
2. **Accept** (Required) - Указывает желаемый формат ответа
```http
Accept: application/json
```
3. **Content-Type** (Required для POST/PUT/PATCH) - Указывает формат тела запроса
```http
Content-Type: application/json
```
### Полный пример headers
**GET Request:**
```http
GET /api/v1/workflows HTTP/1.1
Host: your-instance.app.n8n.cloud
X-N8N-API-KEY: n8n_api_1234567890abcdef
Accept: application/json
```
**POST Request:**
```http
POST /api/v1/workflows HTTP/1.1
Host: your-instance.app.n8n.cloud
X-N8N-API-KEY: n8n_api_1234567890abcdef
Content-Type: application/json
Accept: application/json
{
"name": "My Workflow",
"nodes": [...],
"connections": {...}
}
```
---
## Примеры запросов
### cURL
**n8n Cloud:**
```bash
curl -X GET \
'https://your-instance.app.n8n.cloud/api/v1/workflows?active=true' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: your_api_key_here'
```
**Self-Hosted:**
```bash
curl -X GET \
'https://n8n.example.com/api/v1/workflows?active=true' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: your_api_key_here'
```
**С localhost:**
```bash
curl -X GET \
'http://localhost:5678/api/v1/workflows' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: your_api_key_here'
```
### JavaScript / Node.js
**Используя axios:**
```javascript
const axios = require('axios');
const N8N_API_KEY = 'your_api_key_here';
const N8N_HOST = 'https://your-instance.app.n8n.cloud';
async function getWorkflows() {
try {
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
console.log('Workflows:', response.data);
return response.data;
} catch (error) {
if (error.response?.status === 401) {
console.error('Authentication failed. Check your API key.');
} else {
console.error('Error:', error.message);
}
throw error;
}
}
getWorkflows();
```
**Используя fetch (Node.js 18+):**
```javascript
const N8N_API_KEY = 'your_api_key_here';
const N8N_HOST = 'https://your-instance.app.n8n.cloud';
async function getWorkflows() {
try {
const response = await fetch(`${N8N_HOST}/api/v1/workflows`, {
method: 'GET',
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
if (!response.ok) {
if (response.status === 401) {
throw new Error('Authentication failed. Check your API key.');
}
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log('Workflows:', data);
return data;
} catch (error) {
console.error('Error:', error.message);
throw error;
}
}
getWorkflows();
```
**Создание reusable API client:**
```javascript
const axios = require('axios');
class N8NApiClient {
constructor(apiKey, host) {
this.apiKey = apiKey;
this.host = host;
this.client = axios.create({
baseURL: `${host}/api/v1`,
headers: {
'X-N8N-API-KEY': apiKey,
'Accept': 'application/json',
'Content-Type': 'application/json'
}
});
}
async getWorkflows(options = {}) {
const response = await this.client.get('/workflows', { params: options });
return response.data;
}
async createWorkflow(workflowData) {
const response = await this.client.post('/workflows', workflowData);
return response.data;
}
async getExecutions(options = {}) {
const response = await this.client.get('/executions', { params: options });
return response.data;
}
async getTags(options = {}) {
const response = await this.client.get('/tags', { params: options });
return response.data;
}
}
// Использование
const client = new N8NApiClient(
'your_api_key_here',
'https://your-instance.app.n8n.cloud'
);
// Получить workflows
const workflows = await client.getWorkflows({ active: true });
// Создать workflow
const newWorkflow = await client.createWorkflow({
name: 'Test Workflow',
nodes: [...],
connections: {...}
});
```
### Python
**Используя requests:**
```python
import requests
N8N_API_KEY = 'your_api_key_here'
N8N_HOST = 'https://your-instance.app.n8n.cloud'
def get_workflows():
try:
response = requests.get(
f'{N8N_HOST}/api/v1/workflows',
headers={
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
)
response.raise_for_status()
print('Workflows:', response.json())
return response.json()
except requests.exceptions.HTTPError as error:
if error.response.status_code == 401:
print('Authentication failed. Check your API key.')
else:
print(f'HTTP error: {error}')
raise
except requests.exceptions.RequestException as error:
print(f'Error: {error}')
raise
get_workflows()
```
**Создание Python API client:**
```python
import requests
from typing import Dict, List, Optional
class N8NApiClient:
def __init__(self, api_key: str, host: str):
self.api_key = api_key
self.host = host
self.base_url = f'{host}/api/v1'
self.session = requests.Session()
self.session.headers.update({
'X-N8N-API-KEY': api_key,
'Accept': 'application/json',
'Content-Type': 'application/json'
})
def get_workflows(self, params: Optional[Dict] = None) -> Dict:
response = self.session.get(f'{self.base_url}/workflows', params=params)
response.raise_for_status()
return response.json()
def create_workflow(self, workflow_data: Dict) -> Dict:
response = self.session.post(f'{self.base_url}/workflows', json=workflow_data)
response.raise_for_status()
return response.json()
def get_executions(self, params: Optional[Dict] = None) -> Dict:
response = self.session.get(f'{self.base_url}/executions', params=params)
response.raise_for_status()
return response.json()
def get_tags(self, params: Optional[Dict] = None) -> Dict:
response = self.session.get(f'{self.base_url}/tags', params=params)
response.raise_for_status()
return response.json()
# Использование
client = N8NApiClient(
'your_api_key_here',
'https://your-instance.app.n8n.cloud'
)
# Получить workflows
workflows = client.get_workflows({'active': True})
# Создать workflow
new_workflow = client.create_workflow({
'name': 'Test Workflow',
'nodes': [...],
'connections': {...}
})
```
### PHP
```php
<?php
$n8nApiKey = 'your_api_key_here';
$n8nHost = 'https://your-instance.app.n8n.cloud';
function getWorkflows($apiKey, $host) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/api/v1/workflows");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-N8N-API-KEY: ' . $apiKey,
'Accept: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($httpCode === 401) {
throw new Exception('Authentication failed. Check your API key.');
}
curl_close($ch);
return json_decode($response, true);
}
try {
$workflows = getWorkflows($n8nApiKey, $n8nHost);
print_r($workflows);
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
?>
```
---
## Безопасность
### Лучшие практики безопасности
#### 1. Хранение API ключей
**❌ НИКОГДА не делайте:**
```javascript
// НЕ храните в коде
const API_KEY = 'n8n_api_1234567890abcdef';
// НЕ коммитьте в git
git add config.js // содержит API ключ
```
**✅ ВСЕГДА делайте:**
```javascript
// Используйте environment variables
const API_KEY = process.env.N8N_API_KEY;
// Используйте .env файлы (добавьте .env в .gitignore)
require('dotenv').config();
const API_KEY = process.env.N8N_API_KEY;
// Используйте secret management системы
// - AWS Secrets Manager
// - Azure Key Vault
// - HashiCorp Vault
// - Google Secret Manager
```
**Пример .env файла:**
```bash
# .env
N8N_API_KEY=your_api_key_here
N8N_HOST=https://your-instance.app.n8n.cloud
```
**Пример .gitignore:**
```
# .gitignore
.env
.env.local
.env.*.local
config.json
secrets.json
```
#### 2. HTTPS обязателен
**❌ НИКОГДА:**
```bash
# НЕ используйте HTTP для production
curl http://n8n.example.com/api/v1/workflows \
-H 'X-N8N-API-KEY: your_key'
```
**✅ ВСЕГДА:**
```bash
# ВСЕГДА используйте HTTPS
curl https://n8n.example.com/api/v1/workflows \
-H 'X-N8N-API-KEY: your_key'
```
**Почему HTTPS важен:**
- API ключи передаются в открытом виде в headers
- HTTP трафик может быть перехвачен
- HTTPS шифрует весь трафик между клиентом и сервером
#### 3. Ротация ключей
**Регулярно меняйте API ключи:**
```
Рекомендуемый график:
- Production: каждые 90 дней
- Staging: каждые 180 дней
- Development: по необходимости
```
**Процесс ротации:**
1. Создайте новый API ключ в n8n
2. Обновите все системы с новым ключом
3. Протестируйте работоспособность
4. Удалите старый ключ
#### 4. Минимальные права доступа
**Best Practice:**
- Создавайте отдельные API ключи для разных целей
- Используйте описательные имена для ключей
- Удаляйте неиспользуемые ключи
**Примеры:**
```
Production Workflows API Key - для production интеграций
CI/CD Pipeline Key - только для автоматизации
Development Testing Key - для разработки
```
#### 5. Мониторинг и логирование
**Мониторьте:**
- Неудачные попытки аутентификации (401 errors)
- Необычную активность API
- Использование API ключей
**НЕ логируйте:**
```javascript
// ❌ НЕ логируйте API ключи
console.log('API Key:', apiKey);
logger.debug(`Request with key: ${apiKey}`);
// ✅ Логируйте только метаданные
console.log('API request made');
logger.debug('Authentication successful');
```
### Защита от утечек
**Если API ключ скомпрометирован:**
1. **Немедленно** удалите скомпрометированный ключ в n8n Settings
2. Создайте новый API ключ
3. Обновите все системы с новым ключом
4. Проверьте логи на подозрительную активность
5. Измените другие credentials если необходимо
---
## Troubleshooting
### 401 Unauthorized
**Проблема:** Получаете `401 Unauthorized` ответ
**Причины и решения:**
1. **Неверный API ключ**
```bash
# Проверьте правильность ключа
echo $N8N_API_KEY # Должен быть без пробелов и лишних символов
```
2. **API ключ не в header**
```bash
# Убедитесь что header указан
curl -X GET 'https://n8n.example.com/api/v1/workflows' \
-H 'X-N8N-API-KEY: your_key' # Header присутствует
```
3. **Опечатка в названии header**
```bash
# ❌ Неправильно
-H 'X-N8N-APIKEY: your_key' # Отсутствует дефис
-H 'N8N-API-KEY: your_key' # Отсутствует X-
# ✅ Правильно
-H 'X-N8N-API-KEY: your_key'
```
4. **API ключ удален**
- Проверьте что ключ все еще существует в n8n Settings
- Создайте новый ключ если старый удален
### 403 Forbidden
**Проблема:** Получаете `403 Forbidden` ответ
**Причины:**
- Public API отключен (`N8N_PUBLIC_API_DISABLED=true`)
- Недостаточно прав у API ключа
**Решение:**
```bash
# Self-hosted: проверьте environment variables
echo $N8N_PUBLIC_API_DISABLED # Должно быть пусто или false
```
### Connection Issues
**Проблема:** Не можете подключиться к API
**Решения:**
1. **Проверьте URL:**
```bash
# Cloud
https://your-instance.app.n8n.cloud/api/v1
# Self-hosted
https://n8n.example.com/api/v1
# Localhost
http://localhost:5678/api/v1
```
2. **Проверьте доступность:**
```bash
# Проверьте что сервер доступен
curl https://n8n.example.com/api/v1/workflows \
-H 'X-N8N-API-KEY: your_key' \
-v # Verbose mode для деталей
```
3. **Проверьте HTTPS certificate (self-hosted):**
```bash
# Игнорировать SSL ошибки для тестирования (НЕ для production!)
curl -k https://n8n.example.com/api/v1/workflows \
-H 'X-N8N-API-KEY: your_key'
```
---
## Best Practices
### 1. Централизованная конфигурация
```javascript
// config.js
module.exports = {
n8n: {
apiKey: process.env.N8N_API_KEY,
host: process.env.N8N_HOST || 'https://your-instance.app.n8n.cloud',
apiVersion: 'v1'
}
};
// app.js
const config = require('./config');
const apiClient = new N8NApiClient(config.n8n.apiKey, config.n8n.host);
```
### 2. Error Handling
```javascript
async function makeApiRequest(url, options) {
try {
const response = await fetch(url, {
...options,
headers: {
'X-N8N-API-KEY': process.env.N8N_API_KEY,
'Accept': 'application/json',
...options.headers
}
});
if (!response.ok) {
// Специфичная обработка ошибок
if (response.status === 401) {
throw new Error('Invalid API key');
}
if (response.status === 404) {
throw new Error('Resource not found');
}
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return await response.json();
} catch (error) {
console.error('API request failed:', error.message);
throw error;
}
}
```
### 3. Retry Logic
```javascript
async function apiRequestWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await makeApiRequest(url, options);
} catch (error) {
// Не retry на 401/403 (проблемы с аутентификацией)
if (error.message.includes('401') || error.message.includes('403')) {
throw error;
}
// Последняя попытка - throw error
if (i === maxRetries - 1) {
throw error;
}
// Exponential backoff
const delay = Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
```
### 4. Testing
```javascript
// Используйте mock API ключ для тестов
if (process.env.NODE_ENV === 'test') {
process.env.N8N_API_KEY = 'test_api_key_mock';
process.env.N8N_HOST = 'http://localhost:5678';
}
// test.js
describe('N8N API Client', () => {
it('should authenticate with valid API key', async () => {
const client = new N8NApiClient(
'test_key',
'http://localhost:5678'
);
// Mock HTTP request
// Verify X-N8N-API-KEY header is set
});
});
```
---
## Дополнительные ресурсы
### Официальная документация
- [n8n API Authentication](https://docs.n8n.io/api/authentication/)
- [n8n API Reference](https://docs.n8n.io/api/api-reference/)
### Связанные документы
- [01-OVERVIEW.md](./01-OVERVIEW.md) - Обзор n8n REST API
- [03-PAGINATION.md](./03-PAGINATION.md) - Пагинация результатов
- [10-WORKFLOWS-API.md](./10-WORKFLOWS-API.md) - Workflows API endpoints
---
**Последнее обновление:** 2025-12-25
**Версия документации:** 1.0
**Подготовлено:** James (Dev Agent) с использованием Context7 MCP Server
**Источники:**
- [n8n API Authentication Documentation](https://docs.n8n.io/api/authentication/)
