N8N_ENCRYPTION_KEY : la clé qui protège vos credentials n8n — et comment ne jamais la perdre

C'est souvent le même scénario qui amène ici. Vous venez de migrer votre instance n8n sur un nouveau serveur, ou de la réinstaller après un incident. La base de données est bien restaurée : les workflows sont là, l'historique aussi. Puis vous lancez un workflow, et chaque credential renvoie le même message : « Credentials could not be decrypted ». Rien n'est corrompu, rien n'a disparu — simplement, la clé de chiffrement a changé, et sans elle, les credentials stockés en base sont illisibles. Par conception.

Ce guide explique comment n8n protège vos credentials, pourquoi N8N_ENCRYPTION_KEY est la pièce la plus critique — et la plus oubliée — d'une installation self-hosted, et comment ne jamais vivre ce scénario, ou en sortir proprement s'il est déjà trop tard.

Ce que n8n chiffre, et pourquoi

Une instance n8n accumule vite des dizaines de credentials : clés API OpenAI, tokens Slack, mots de passe SMTP, accès PostgreSQL… Stockés en clair dans la base, ils partiraient avec le premier dump venu — un prestataire, une sauvegarde qui traîne sur un bucket mal configuré, un accès de trop.

n8n évite ce risque en chiffrant les credentials avant de les écrire en base. Un SELECT sur la table des credentials ne révèle que des blobs illisibles. Pour les déchiffrer, il faut la clé de chiffrement, que n8n obtient de deux façons :

• Fournie explicitement via la variable d'environnement N8N_ENCRYPTION_KEY — le cas recommandé, on y revient.
• Générée automatiquement au premier démarrage si la variable est absente, puis stockée dans le fichier de configuration du répertoire de données n8n (~/.n8n/config, qui vit dans un volume Docker en installation conteneurisée).

Ce second cas est le mode par défaut, et c'est lui qui piège tout le monde : la clé existe, elle fonctionne, mais personne ne sait qu'elle est là. Le jour où le volume Docker saute, où le serveur est réinstallé, ou où la migration ne copie que la base, la nouvelle instance génère une nouvelle clé — et tous les credentials chiffrés avec l'ancienne deviennent indéchiffrables.

Il faut le dire clairement, car c'est contre-intuitif : une sauvegarde de la base de données seule ne protège pas vos credentials. La base sans la clé contient des workflows parfaitement restaurables et des credentials parfaitement inutilisables.

La règle d'or : fixer la clé explicitement dès l'installation

La parade tient en deux gestes, à faire une fois pour toutes au moment de l'installation (ou dès maintenant si votre instance tourne déjà, voir plus bas).

1. Générer une clé robuste. Une valeur aléatoire longue, produite par un vrai générateur :

openssl rand -hex 24

2. La fixer dans la configuration, via le .env référencé par votre docker-compose.yml :

# docker-compose.yml (extrait)
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
    # ... reste de la configuration

# .env
N8N_ENCRYPTION_KEY=la_valeur_generee_par_openssl

3. La sauvegarder dans un gestionnaire de mots de passe (Bitwarden, 1Password, Vaultwarden…), au même titre que le mot de passe root du serveur. Pas dans un fichier texte sur le serveur lui-même — si le serveur meurt, la clé meurt avec.

Attention à un point : si votre instance tourne déjà avec une clé auto-générée, ne fixez pas une nouvelle valeur dans N8N_ENCRYPTION_KEY — vous provoqueriez exactement l'erreur que ce guide cherche à éviter. Récupérez la clé existante dans le fichier ~/.n8n/config du conteneur (par exemple docker exec -it n8n cat /home/node/.n8n/config), et c'est cette valeur-là que vous reportez dans le .env. La clé ne change pas : elle devient simplement explicite, et impossible à perdre par accident de volume.

Ce réflexe rejoint une leçon ancienne de la recherche en sécurité : la cryptographie échoue rarement sur les mathématiques, presque toujours sur la gestion humaine des clés. L'étude classique de Whitten et Tygar, Why Johnny Can't Encrypt: A Usability Evaluation of PGP 5.0 (USENIX Security, 1999 — voir sur Google Scholar), montrait déjà que la majorité des participants échouaient à utiliser correctement un outil de chiffrement pourtant conçu pour le grand public — non que l'algorithme fût faible, mais la manipulation des clés leur échappait. Le « Credentials could not be decrypted » d'une instance migrée sans sa clé en est l'illustration exacte : l'algorithme a parfaitement fait son travail ; c'est la clé qui n'a pas suivi.

Sauvegarde complète = base de données + clé

Une sauvegarde n8n digne de ce nom comporte donc deux éléments indissociables :

• La base de données, qui contient workflows, credentials chiffrés et historique — la procédure complète est dans notre guide sauvegarde et restauration PostgreSQL.
• La clé de chiffrement, sans laquelle la moitié credentials de cette base est du bruit.

Si la clé est fixée dans le .env comme recommandé, il suffit d'inclure ce fichier (ou son contenu, via le gestionnaire de mots de passe) dans la procédure de sauvegarde. Sinon, c'est le volume Docker contenant ~/.n8n qu'il faut sauvegarder en plus de la base — précisément celui que la plupart des scripts oublient, parce qu'on pense « les données sont dans PostgreSQL » et qu'un répertoire de config ne semble rien contenir d'irremplaçable. Il contient la seule copie de la clé.

Testez la restauration au moins une fois : base restaurée et clé sur une instance jetable, un credential ouvert, un workflow exécuté. Une sauvegarde jamais testée est une hypothèse, pas une sauvegarde.

Migration : restaurer la base ET réutiliser la même clé

Toute migration d'instance — changement de serveur, passage de SQLite à PostgreSQL, ou migration de n8n Cloud vers du self-hosted — suit la même règle : la nouvelle instance doit démarrer avec la clé de l'ancienne, fournie via N8N_ENCRYPTION_KEY, avant le premier lancement. L'ordre compte : si la nouvelle instance démarre une fois sans la clé, elle en génère une, et il faudra la reconfigurer proprement avant que les credentials restaurés redeviennent lisibles.

La check-list de migration côté credentials :

1. Récupérer la clé de l'instance source (.env, ou ~/.n8n/config si elle était auto-générée).
2. La placer dans le .env de l'instance cible.
3. Restaurer la base de données.
4. Démarrer, ouvrir un credential existant pour vérifier qu'il se déchiffre, exécuter un workflow de test.

Le même principe vaut pour une simple mise à jour de version : la clé ne change pas d'une version à l'autre, mais une mise à jour menée en recréant les conteneurs sans préserver le volume ou le .env peut la faire disparaître — notre guide mettre à jour n8n sans rien casser détaille la procédure qui évite ce genre de dégât collatéral.

Queue mode : une seule clé pour le main et tous les workers

Si votre instance tourne en mode queue avec Redis et des workers, la contrainte s'étend : le processus principal et chaque worker lisent les mêmes credentials chiffrés dans la même base, donc tous doivent démarrer avec exactement la même N8N_ENCRYPTION_KEY. Un worker qui reçoit une clé différente (ou pas de clé, donc une clé auto-générée à lui) acceptera les jobs mais échouera à déchiffrer les credentials au moment de les exécuter.

C'est un argument de plus pour le .env partagé : un seul fichier, référencé par les services n8n, n8n-worker et consorts, et l'incohérence devient impossible.

Clé perdue : ce qui est récupérable, ce qui ne l'est pas

Si la clé est définitivement perdue — volume supprimé, serveur disparu, aucune sauvegarde du fichier de config — il faut être honnête : les credentials sont irrécupérables. Aucun outil, aucun accès à la base ne permet de les déchiffrer sans la clé ; c'est exactement la garantie que le chiffrement offre, et elle joue aussi contre vous.

Ce qui reste intact :

• Les workflows, dans leur intégralité : logique, nodes, connexions, réglages.
• L'historique d'exécution et le reste de la base.

La marche à suivre : générer une nouvelle clé, la fixer dans N8N_ENCRYPTION_KEY, la sauvegarder (cette fois), puis re-saisir chaque credential à la main. C'est fastidieux, mais c'est aussi l'occasion de faire le ménage : régénérez les clés API côté services plutôt que de re-coller les anciennes, supprimez les credentials orphelins, notez qui a accès à quoi — la démarche complète est dans notre guide sécuriser ses credentials API dans n8n. Beaucoup d'instances traînent des accès accordés « pour tester » deux ans plus tôt ; l'inventaire forcé a au moins cette vertu.

Changer de clé volontairement : la rotation, sans illusion

Peut-on faire tourner la clé par précaution, comme un mot de passe ? n8n ne propose pas de mécanisme natif de re-chiffrement de la base avec une nouvelle clé : changer la valeur de N8N_ENCRYPTION_KEY ne re-chiffre rien, cela rend simplement les credentials existants illisibles.

En pratique, une rotation revient donc à re-créer les credentials : inventorier l'existant pendant que l'ancienne clé fonctionne encore, basculer sur la nouvelle, puis re-saisir les credentials un par un. C'est le même chantier qu'une clé perdue, mais planifié. Sauf compromission avérée, le jeu en vaut rarement la chandelle pour une petite instance ; si vous vous y engagez, procédez sur une instance de test d'abord, et référez-vous à la documentation officielle n8n pour l'état actuel de ce que l'outil permet.

Ce que N8N_ENCRYPTION_KEY n'est pas

Deux confusions reviennent souvent :

• Ce n'est pas une variable de configuration comme les autres. Les variables d'environnement n8n se changent et s'ajustent au fil du temps — URL du webhook, fuseau horaire, limites d'exécution. N8N_ENCRYPTION_KEY est la seule dont la modification détruit fonctionnellement des données : on la fixe une fois, on la sauvegarde, on n'y touche plus.
• Ce n'est pas l'authentification de l'interface. La clé protège les credentials stockés en base contre une lecture directe de la base ; elle ne protège pas l'accès à l'interface n8n (comptes utilisateurs, SSO, reverse proxy). Deux couches distinctes, et il faut les deux.

Pièges fréquents

• Laisser n8n générer la clé sans jamais la noter : le mode par défaut fonctionne parfaitement… jusqu'à la première migration ou perte de volume. Fixez N8N_ENCRYPTION_KEY explicitement, dès l'installation.
• Sauvegarder la base mais pas la clé : le script de backup couvre PostgreSQL et ignore le volume ~/.n8n — la moitié credentials de la sauvegarde est inutilisable le jour venu.
• Fixer une nouvelle valeur sur une instance existante en croyant « régulariser » : les credentials chiffrés avec l'ancienne clé auto-générée deviennent illisibles. Récupérez d'abord la clé existante dans ~/.n8n/config.
• Démarrer la nouvelle instance avant d'avoir posé la clé lors d'une migration : une clé auto-générée s'installe, et le « Credentials could not be decrypted » apparaît malgré une base correctement restaurée.
• Des workers en mode queue avec des clés différentes : les jobs partent, le déchiffrement échoue à l'exécution. Un seul .env partagé par tous les services.
• Stocker la clé uniquement sur le serveur qu'elle protège : dans le .env du serveur et dans un gestionnaire de mots de passe externe, sinon la clé disparaît avec la machine.
• Committer le .env dans un dépôt Git : la clé est un secret au même titre qu'un mot de passe de base de données — hors du versioning, toujours.

En résumé

N8N_ENCRYPTION_KEY est la variable la plus critique d'une installation n8n self-hosted : elle chiffre tous les credentials en base, et sans elle, une sauvegarde ou une migration ne restaure que des workflows sans accès. La discipline tient en trois gestes — générer une clé robuste (openssl rand -hex 24), la fixer explicitement dans le .env dès l'installation, la conserver dans un gestionnaire de mots de passe — et en une règle : base de données et clé de chiffrement voyagent toujours ensemble, en sauvegarde comme en migration. Si vous héritez d'une clé perdue, les workflows survivent, les credentials se re-saisissent, et l'inventaire forcé des accès qui en découle est exactement le genre de chantier que formalise le Pack Conformité & Audit (149 €) : qui a accès à quoi, où vivent les secrets, qu'est-ce qui est tracé — la gestion de la clé de chiffrement n'en est que la première ligne.