В n8n «ключом» называют как минимум три разные вещи: публичный API Key для управления экземпляром n8n, OpenAI-совместимый ключ для вызова моделей и N8N_ENCRYPTION_KEY, защищающий учётные данные в базе. Назначение у них разное, и хранение не на своём месте создаёт проблемы безопасности. Многие обращения «настройка не работает» на деле вызваны тем, что один тип приняли за другой.

Материал идёт по порядку «что это, где хранить, как ротировать, как искать причину сбоя» и рассчитан на команды с самостоятельным хостингом и экземпляры для совместной работы.

Примечание: n8n — товарный знак n8n GmbH, OpenAI — товарный знак OpenAI, Inc. Материал носит технический характер и не означает подчинения или сотрудничества с указанными компаниями. Цены и доступные модели — на странице цены на модели.

1. Сначала различите три типа ключей

Тип Назначение Где хранится Типичный заголовок
Публичный API Key n8n Вызов REST API самого n8n, управление процессами и выполнениями Создаётся в интерфейсе n8n, хранится у вызывающей стороны X-N8N-API-KEY
Ключ сервиса моделей Вызов OpenAI-совместимого интерфейса Учётные данные n8n, шифруются в базе Authorization: Bearer ...
N8N_ENCRYPTION_KEY Шифрование учётных данных в базе Переменная окружения или файл конфигурации .n8n Не отправляется в заголовке

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

2. Как создать публичный API Key n8n

Вход находится в Settings > n8n API: нажмите Create an API key, заполните Label и срок действия. Официальная документация указывает, что в облачном бесплатном пробном периоде публичный API недоступен; в корпоративной версии можно выбрать Scopes и ограничить ключ конкретными ресурсами и действиями, например workflow:read или credential:list. Ключ не корпоративной версии по умолчанию имеет полный доступ к ресурсам аккаунта, поэтому тем важнее контролировать владельца.

При вызове ключ передаётся в заголовке X-N8N-API-KEY, путь обычно /api/v1:

curl -sS "https://ваш-домен-n8n/api/v1/workflows?active=true" \
  -H "accept: application/json" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Несколько правил:

  1. Один ключ — одно назначение: CI, мониторинг или внутренний инструмент.
  2. Устанавливайте срок действия и ротируйте ключ до истечения.
  3. Не записывайте ключ во фронтенд-код, параметры URL или журналы.
  4. Не заменяйте публичным API Key ключ модели.
  5. Если публичный API не нужен, отключите его через N8N_PUBLIC_API_DISABLED=true.

3. Учётные данные модели: ключ должен лежать в Credentials

Для подключения OpenAI-совместимого сервиса используйте учётные данные типа OpenAI и заполните API Key и Base URL. Адрес шлюза обычно указывают до /v1, например https://ai.zhongshangqihang.com/v1. Organization ID нужен только для официального OpenAI с несколькими организациями; при работе через совместимый шлюз поле обычно пустое. Учётные данные также поддерживают дополнительные пользовательские заголовки — это удобно, если шлюз требует отдельный идентификатор.

Не допускайте появления ключа в следующих местах:

  • в узлах Code, Set или промптах;
  • в обычных полях JSON процесса;
  • в ответах Webhook, журналах выполнения и уведомлениях об ошибках;
  • на скриншотах, записях экрана и в общих документах.

Экспорт процесса обычно не включает сами учётные данные, но ключ, записанный в параметрах узла, уходит вместе с JSON. Перед передачей процесса коллегам поищите sk- и распространённые префиксы ключей.

4. Переменные окружения: конфигурация — да, хранилище секретов — нет

Самостоятельный n8n использует переменные окружения для порта, базы, адреса Webhook и другого. Чувствительные значения вроде N8N_ENCRYPTION_KEY и пароля базы тоже следует передавать через переменные окружения или сервис управления секретами, а не писать в Compose-файл и коммитить в Git. Часть переменных поддерживает суффикс _FILE, когда значение читается из отдельного файла.

Но переменные окружения не являются безопасным хранилищем секретов. Документация n8n прямо предупреждает, что переменные окружения в n8n не защищены и могут быть доступны пользователям; поэтому массовая передача учётных данных через CREDENTIALS_OVERWRITE_DATA не рекомендуется, надёжнее использовать endpoint перезаписи с аутентификацией.

Если бизнес-пользователям разрешено редактировать процессы, включите N8N_BLOCK_ENV_ACCESS_IN_NODE=true, чтобы выражения и узлы Code не читали переменные окружения. По умолчанию значение false; после изменения перезапустите экземпляр. Учтите также, что история выполнений сохраняет вход и выход узлов: чувствительные поля нужно маскировать до попадания в n8n или сокращать срок хранения через EXECUTIONS_DATA_MAX_AGE.

5. Ключ шифрования: потеряете его — не прочитаете учётные данные

При первом запуске n8n автоматически создаёт ключ шифрования, сохраняет его в каталоге ~/.n8n и использует для шифрования учётных данных, записываемых в базу. Можно задать собственное значение через N8N_ENCRYPTION_KEY. Официальная документация прямо указывает: при потере этого ключа все сохранённые учётные данные прочитать невозможно.

Поэтому резервное копирование делается парой: база и ключ шифрования хранятся отдельно, доступ к ним контролируется раздельно. Если сохранить только базу, после восстановления без исходного ключа учётные данные всё равно не расшифруются; если сохранить только ключ, потеря базы делает его бесполезным.

В режиме очереди основной экземпляр и все worker должны использовать один N8N_ENCRYPTION_KEY, иначе worker не расшифрует учётные данные, записанные основным экземпляром. Запишите это в план развёртывания до масштабирования.

Начиная с n8n 3.0 ротация ключа шифрования данных поддерживается по умолчанию; в 2.x нужно вручную включить N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true и обеспечить одинаковое значение на всех узлах. Перед ротацией сделайте полную резервную копию базы; документация также предупреждает, что после включения нового формата нельзя откатываться на старую версию. Вход ротации — Settings > Data Encryption Keys.

6. Ротация и минимальные права

Управление ключами — это не «настроил один раз и забыл», а постоянное сужение прав:

  • По средам: разработка, тест и производство используют разные ключи; производственный ключ не хранится на машине разработчика.
  • По проектам: один проект — один ключ, расход и квоты наблюдаются отдельно.
  • По людям: у каждого свой ключ, при увольнении отзывается только он, без общего ключа на всех.
  • Короткий срок: публичным API Key задаётся срок действия; ключи моделей также регулярно ротируются.
  • Сначала создать, потом удалить: при ротации создайте новый ключ, обновите вызывающую сторону, проверьте и только затем отзывайте старый.
  • Минимальные права: в корпоративной версии отмечайте только необходимые scopes публичного API Key; роли проекта дают только нужные права.
  • Ограничение назначения: часть учётных данных на основе Web API позволяет задать разрешённые домены HTTP-запросов и снизить риск использования ключа на других адресах.
  • Аудит: сохраняйте записи о создании, использовании и удалении ключей, оповещайте об аномальном расходе.

7. Роли команды и совместное использование учётных данных

Роли экземпляра n8n включают Owner, Admin и Member; проекты и учётные данные можно изолировать по проектам. В Community Edition учётные данные находятся в личном пространстве; версии с поддержкой проектов позволяют поместить их в проект и использовать участникам проекта. Пользовательские роли и детальные права корпоративного уровня относятся к Enterprise; точный состав — в официальной документации.

Практические рекомендации:

  1. Оставляйте Owner только нескольким людям, повседневные операции выполняйте как Admin или Member.
  2. Бизнес-процессы храните в проектах, учётные данные — тоже в проектах, а не в личном пространстве.
  3. Называйте учётные данные по шаблону «сервис-среда-назначение», например «шлюз-производство-сводка-поддержки».
  4. Не делитесь учётной записью и не передавайте личный ключ коллегам.
  5. Включите MFA, принудительный HTTPS в производстве и N8N_SECURE_COOKIE=true.
  6. Используйте внешний task runner в производстве; официальная документация помечает internal-режим как нерекомендуемый и устаревший с 3.0.

В корпоративной версии также доступно внешнее хранилище секретов: значения из 1Password Connect, AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager, HashiCorp Vault или Infisical можно ссылать в поля учётных данных. Ссылка разрешается только в этом поле и не появляется в других выражениях процесса.

8. Типовая диагностика

Симптом Возможная причина Действие
Учётные данные не расшифровываются Изменён N8N_ENCRYPTION_KEY или восстановлена старая база Вернуть исходный ключ; восстановить согласованную резервную копию
Публичный API возвращает 401 Отсутствует или просрочен X-N8N-API-KEY Создать ключ заново, проверить заголовок
Публичный API возвращает 403 Недостаточно scopes в корпоративной версии Добавить нужный scope, например workflow:read
Запрос к модели возвращает 401 Ключ модели неверен, просрочен или учётные данные не выбраны Перезаписать ключ, проверить привязку к узлу
Переменная окружения не читается Переменная не передана в контейнер или доступ из узла отключён Проверить окружение Compose и N8N_BLOCK_ENV_ACCESS_IN_NODE
Worker сообщает об ошибке расшифровки Ключ worker не совпадает с основным экземпляром Привести N8N_ENCRYPTION_KEY к одному значению и перезапустить

Начинайте диагностику с вопроса «что менялось последним»: замена ключа, изменение Base URL, обновление версии и миграция базы чаще всего вызывают проблемы с ключами. Меняйте одну переменную за раз и сразу проверяйте минимальным запросом.

Частые вопросы

API Key n8n и API Key OpenAI — одно и то же?

Нет. API Key n8n вызывает REST API самого n8n и передаётся в заголовке X-N8N-API-KEY; OpenAI-совместимый ключ вызывает интерфейс модели, хранится в учётных данных и отправляется узлом как Bearer.

Поддерживает ли публичный API Key n8n ограничение прав?

В корпоративной версии поддерживаются Scopes с ограничением до конкретных ресурсов и действий; официально рекомендуется выдавать только необходимый объём. Ключ не корпоративной версии по умолчанию имеет полный доступ к ресурсам аккаунта, поэтому разделяйте его по людям и назначению и задавайте срок действия.

Что произойдёт при изменении N8N_ENCRYPTION_KEY?

Ранее зашифрованные учётные данные обычно перестанут расшифровываться. Значение нужно зафиксировать при первом развёртывании и сохранить резервную копию; при необходимости замены сначала оцените официальную функцию ротации ключей и не меняйте переменную окружения напрямую.

Можно ли хранить ключ в переменной окружения и использовать в процессе?

Можно, но не рекомендуется. Документация n8n предупреждает, что переменные окружения не защищены и могут быть доступны пользователям. Надёжнее использовать учётные данные или внешнее хранилище секретов; если без переменной не обойтись, включите N8N_BLOCK_ENV_ACCESS_IN_NODE и ограничьте доступ к экземпляру.

Допустим ли общий ключ модели на команду?

Не рекомендуется. По общему ключу нельзя разделить расход, утечка одного затрагивает всех, а отозвать доступ отдельному человеку невозможно. Разделяйте ключи по проектам, средам или людям, используя квоты и отчёты шлюза: так и затраты, и безопасность управляемее.

Дальше

Систему ключей n8n можно запомнить одной фразой: публичный API Key управляет экземпляром, ключ модели — вызовами, ключ шифрования — базой. Храните их раздельно, ротируйте по отдельности и дополните ролями проектов, сроками действия и аудитом — тогда настройка будет полной. Для единой точки входа и учёта расхода можно зарегистрироваться в ZSQH AI Gateway; модели и цены — на странице цены на модели.

Полезное чтение: