Как создать api key для n8n

Как создать и настроить API ключ в n8n: полное руководство

API ключ в n8n — это строка символов, которая используется для аутентификации внешних приложений, сервисов или скриптов в вашем экземпляре n8n. В отличие от встроенной аутентификации пользовательского интерфейса, API ключи предназначены для машинного взаимодействия, позволяя автоматизировать управление рабочими процессами, мониторинг и интеграцию с другими системами без необходимости прямого входа в систему. Этот механизм обеспечивает безопасный и контролируемый доступ к REST API n8n.

Предварительные требования и настройка окружения

Перед созданием API ключа необходимо убедиться, что ваш экземпляр n8n правильно настроен для работы с внешним API. По умолчанию API может быть отключен или доступен только через локальный хост.

• Версия n8n: Убедитесь, что используется n8n версии 0.198.0 или выше, так как в этих версиях была значительно переработана система аутентификации и управления API ключами.
• Конфигурационный файл environment variables: Основные настройки выполняются через переменные окружения, чаще всего задаваемые в файле .env в корневой директории установки n8n или в переменных среды контейнера Docker.

Активация и настройка API в n8n

Для того чтобы API был доступен извне, необходимо задать соответствующие переменные окружения. Ниже приведены ключевые параметры.

Переменная окружения	Значение по умолчанию	Описание и рекомендуемое значение
N8N_PROTOCOL	http	Протокол для доступа к n8n. Для продакшн-среды используйте https.
N8N_HOST	localhost	Хост, на котором работает n8n. Для внешнего доступа укажите домен или публичный IP-адрес (например, n8n.yourcompany.com).
N8N_PORT	5678	Порт веб-интерфейса и API. Убедитесь, что порт открыт в файрволе.
N8N_ENDPOINT_REST_API	rest	Базовый путь для REST API эндпоинтов. Менять не рекомендуется без необходимости.
EXECUTIONS_DATA_PRUNE	false	Автоматическая очистка данных выполнений. Для продакшена рекомендуется настроить.
N8N_ENCRYPTION_KEY	—	Обязательный параметр. Ключ для шифрования чувствительных данных. Должен быть строкой длиной 32 символа. Задается один раз при первом запуске.

Пример конфигурации для продакшн-среды в файле .env:

• N8N_PROTOCOL=https
• N8N_HOST=n8n.yourdomain.com
• N8N_PORT=443
• N8N_ENCRYPTION_KEY=your_32_char_super_secure_encryption_key
• WEBHOOK_URL=https://n8n.yourdomain.com/

После изменения переменных окружения перезапустите n8n для применения настроек.

Создание API ключа через пользовательский интерфейс n8n

Самый простой и наглядный способ создания API ключа — использование веб-интерфейса администратора n8n.

1. Войдите в n8n с учетными данными владельца (owner).
2. В левом боковом меню перейдите в раздел «Settings» (Настройки).
3. В открывшемся меню настроек выберите пункт «API».
4. Вы окажетесь на вкладке «Keys». Нажмите кнопку «Add API Key».
5. Откроется форма создания ключа. Заполните обязательные поля:
   • Name: Уникальное, описательное имя для ключа (например, «CI/CD Pipeline» или «External Monitoring»).
   • Scope: Это критически важный параметр, определяющий уровень доступа. Выберите одну из ролей:
     • Owner (Владелец): Полный доступ ко всем операциям, включая управление пользователями, рабочими процессами и настройками системы.
     • Admin (Администратор): Доступ почти ко всем функциям, кроме управления владельцами и некоторых системных настроек.
     • Member (Участник): Может создавать, запускать и управлять своими рабочими процессами, но имеет ограниченный доступ к ресурсам других пользователей и системным настройкам.
6. После выбора Scope нажмите кнопку «Create».
7. ВАЖНО: n8n отобразит сгенерированный API ключ только один раз. Немедленно скопируйте его и сохраните в надежном месте (например, в менеджере паролей). Ключ имеет формат, начинающийся с префикса, например, nk_abc123.... После закрытия окна вы не сможете получить ключ повторно, только создать новый.

Создание API ключа через командную строку (CLI)

Для автоматизации или работы в headless-режиме вы можете создать API ключ с помощью командной строки n8n.

1. Остановите службу n8n, если она запущена.
2. Используйте команду n8n user:create для создания нового пользователя, которому будет принадлежать ключ, или команду n8n api:create для создания ключа для существующего пользователя (в зависимости от версии).
3. Более универсальный способ — использовать команду с указанием email пользователя и роли:

   n8n user:create --email api-user@yourdomain.com --firstName API --lastName User --role owner --password YourSecurePassword

   После создания пользователя вы можете использовать его учетные данные для базовой аутентификации в API или создать для него отдельный API ключ через интерфейс.

Использование API ключа для аутентификации запросов

После получения API ключа его необходимо корректно передавать в HTTP-заголовках каждого запроса к REST API n8n. Существует два основных метода.

Метод аутентификации	HTTP-заголовок	Пример значения заголовка	Примечание
Через заголовок X-N8N-API-KEY	X-N8N-API-KEY	X-N8N-API-KEY: nk_abc123def456ghi789jkl	Рекомендуемый и наиболее безопасный способ, специально предназначенный для n8n.
Через стандартный заголовок Authorization с префиксом «Bearer «	Authorization	Authorization: Bearer nk_abc123def456ghi789jkl	Альтернативный способ, совместимый со многими стандартными HTTP-клиентами и библиотеками.

Пример запроса к API с использованием cURL

Запрос для получения списка рабочих процессов (workflows):

curl -X GET 'https://n8n.yourdomain.com/rest/workflows' 
  -H 'X-N8N-API-KEY: nk_abc123def456ghi789jkl'

Запрос для активации (запуска) существующего рабочего процесса по его ID:

curl -X POST 'https://n8n.yourdomain.com/rest/workflows/abc-workflow-id/activate' 
  -H 'X-N8N-API-KEY: nk_abc123def456ghi789jkl'

Безопасное хранение и управление API ключами

Безопасность API ключей является первостепенной задачей, так как они предоставляют прямой доступ к вашей автоматизации.

• Никогда не храните ключи в коде: Не коммитьте API ключи в системы контроля версий (Git). Используйте переменные окружения или секреты.

  Пример в Node.js
  const API_KEY = process.env.N8N_API_KEY;

• Используйте менеджеры секретов: Для продакшн-сред применяйте такие решения, как HashiCorp Vault, AWS Secrets Manager, Azure Key Vault или аналоги.
• Регулярно ротируйте ключи: Планируйте периодическую замену API ключей (например, каждые 90 дней). В n8n для этого необходимо создать новый ключ, обновить его во всех системах, а затем удалить старый.
• Соблюдайте принцип минимальных привилегий: Всегда назначайте ключу минимально необходимый Scope (роль). Для большинства интеграций достаточно роли «Member».
• Мониторинг использования: Регулярно проверяйте логи n8n на предмет необычной активности, связанной с API ключами.

Основные операции, доступные через REST API

С помощью аутентифицированных API-запросов вы можете управлять практически всеми аспектами n8n. Основные конечные точки (endpoints) включают:

Ресурс (Endpoint)	HTTP Метод	Описание
/rest/workflows	GET, POST	Получить список всех рабочих процессов или создать новый.
/rest/workflows/{id}	GET, PUT, DELETE	Получить, обновить или удалить конкретный рабочий процесс.
/rest/workflows/{id}/activate	POST	Активировать (запустить) рабочий процесс.
/rest/executions	GET	Получить список выполнений (executions) с возможностью фильтрации.
/rest/credentials	GET, POST	Управление учетными данными (credentials). Требует высоких привилегий.

Часто задаваемые вопросы (FAQ)

Где я могу найти созданный API ключ, если я его не скопировал?

Невозможно. n8n, следуя лучшим практикам безопасности, отображает значение ключа только один раз в момент его создания. Если ключ утерян, вы должны создать новый в разделе Settings > API, а затем обновить его во всех системах, где использовался старый. После этого старый ключ следует немедленно удалить.

В чем разница между API ключом и учетными данными пользователя (email/пароль) в n8n?

Это принципиально разные механизмы аутентификации. Учетные данные пользователя (email и пароль) предназначены для входа в веб-интерфейс n8n и предоставляют доступ к полному функционалу в соответствии с ролью пользователя. API ключ — это токен, предназначенный исключительно для машинного взаимодействия с REST API. Он не может быть использован для входа в UI. Ключи имеют строго определенные scope (роли) и обеспечивают более безопасный и отслеживаемый способ интеграции.

Как ограничить доступ API ключа только к определенным рабочим процессам или операциям?

Встроенная система ролей (Scope) n8n не предоставляет детализации на уровне отдельных рабочих процессов. Ключ с ролью «Member» позволит владельцу ключа управлять только теми рабочими процессами, которые созданы под учетной записью пользователя, для которого сгенерирован ключ. Для более тонкого контроля (например, доступ только на чтение или только к одному workflow) необходимо реализовывать собственную промежуточную прокси-службу (middleware), которая будет проверять API ключ и перенаправлять/фильтровать запросы к n8n, либо использовать вебхуки для запуска конкретных процессов без предоставления полного доступа к API.

Можно ли создать несколько API ключей для одного пользователя?

Да, вы можете создать неограниченное количество API ключей для одной учетной записи пользователя. Это полезно для разделения ответственности: например, один ключ с ролью «Member» для CI/CD-пайплайна, другой ключ с ролью «Admin» для системы мониторинга. Каждый ключ можно назвать в соответствии с его назначением, что упрощает управление и отзыв в случае компрометации одного из них.

Как отозвать (удалить) скомпрометированный API ключ?

1. Войдите в веб-интерфейс n8n как владелец или администратор.
2. Перейдите в Settings > API > Keys.
3. Найдите в списке ключ, который необходимо отозвать.
4. Нажмите на иконку корзины (Delete) рядом с именем ключа.
5. Подтвердите удаление. Доступ по этому ключу будет прекращен немедленно.

Почему мои API-запросы возвращают ошибку 401 Unauthorized?

Наиболее распространенные причины:

• Неверный или просроченный API ключ: Проверьте правильность копирования ключа, отсутствие лишних пробелов. Если ключ утерян, создайте новый.
• Неправильный заголовок аутентификации: Убедитесь, что заголовок X-N8N-API-KEY или Authorization отправляется корректно.
• Недостаточные права (Scope): Ключ с ролью «Member» не может выполнять операции, требующие прав «Admin» или «Owner» (например, управление учетными данными или пользователями).
• Неправильный базовый URL: Убедитесь, что запрос отправляется на корректный адрес вашего экземпляра n8n, включая правильный порт и путь /rest.

Поддерживает ли n8n JWT или OAuth для аутентификации API?

Нативная аутентификация API в n8n в текущих версиях (по состоянию на конец 2023 года) построена на собственной системе API ключей. Прямой поддержки JWT или OAuth 2.0 для доступа к внутреннему API не предусмотрено. Однако n8n может выступать в качестве OAuth-клиента или сервера для интеграции со сторонними сервисами в рамках рабочих процессов. Для организации аутентификации через JWT/OAuth к вашему экземпляру n8n потребуется развернуть внешний API-шлюз (например, на основе Kong, Tyk или облачного решения), который будет обрабатывать современные протоколы аутентификации и проксировать запросы к n8n с уже подставленным валидным API ключом.