Dans n8n, le mot « clé » recouvre au moins trois objets : la clé API publique qui administre l'instance, la clé compatible OpenAI qui appelle le service de modèles, et N8N_ENCRYPTION_KEY qui protège les identifiants stockés en base. Leurs usages diffèrent ; les intervertir crée des problèmes de sécurité. Beaucoup de demandes « la configuration ne prend pas effet » viennent d'une confusion entre ces trois clés.

Cet article suit l'ordre « ce que c'est, où la ranger, comment la renouveler, comment diagnostiquer », à destination des équipes auto-hébergées et des instances multi-utilisateurs.

Remarque : n8n est une marque de n8n GmbH et OpenAI une marque d'OpenAI, Inc. Cet article est purement technique, sans affiliation ni coopération avec ces sociétés. Prix et modèles disponibles sont indiqués sur la page tarifs des modèles.

1. Distinguer les trois clés

Type Usage Emplacement En-tête typique
Clé API publique n8n Appeler l'API REST de n8n, gérer workflows et exécutions Créée dans l'interface n8n, conservée par l'appelant X-N8N-API-KEY
Clé de service de modèles Appeler une interface compatible OpenAI Identifiant n8n, chiffré en base Authorization: Bearer ...
N8N_ENCRYPTION_KEY Chiffrer les identifiants en base Variable d'environnement ou fichier de configuration .n8n Jamais envoyée en en-tête

Une clé API publique ne sert pas à appeler un modèle, et une clé de modèle ne sert pas à administrer les workflows n8n. Le mélange produit le plus souvent un 401, ou élargit des permissions qui devaient rester en lecture seule.

2. Créer la clé API publique n8n

L'entrée se trouve dans Settings > n8n API : cliquez sur Create an API key, renseignez le Label et la date d'expiration. La documentation précise que l'API publique n'est pas disponible pendant l'essai gratuit cloud ; l'édition Enterprise permet de choisir des Scopes limitant la clé à des ressources et actions précises comme workflow:read ou credential:list. Hors Enterprise, une clé dispose par défaut d'un accès complet aux ressources du compte : contrôlez d'autant plus qui la détient.

Placez la clé dans l'en-tête X-N8N-API-KEY, le chemin étant généralement /api/v1 :

curl -sS "https://votre-domaine-n8n/api/v1/workflows?active=true" \
  -H "accept: application/json" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Quelques règles :

  1. Une clé pour un seul usage : CI, monitoring ou outil interne.
  2. Fixez une expiration et renouvelez avant échéance.
  3. N'écrivez jamais la clé dans le front-end, les paramètres d'URL ou les journaux.
  4. N'utilisez pas la clé API publique à la place d'une clé de modèle.
  5. Désactivez l'API publique si inutile avec N8N_PUBLIC_API_DISABLED=true.

3. Identifiants de modèle : la clé appartient à l'identifiant

Pour un service compatible OpenAI, utilisez un identifiant de type OpenAI avec API Key et Base URL. L'adresse d'une passerelle se saisit généralement jusqu'à /v1, par exemple https://ai.zhongshangqihang.com/v1. Organization ID ne sert qu'avec un compte OpenAI d'origine multi-organisations ; via une passerelle compatible, laissez vide. L'identifiant accepte aussi des en-têtes personnalisés, utile lorsqu'une passerelle exige un marqueur supplémentaire.

La clé ne doit pas apparaître dans :

  • les nœuds Code, Set ou les prompts ;
  • les champs ordinaires du JSON de workflow ;
  • les réponses de webhook, journaux d'exécution et notifications d'erreur ;
  • les captures d'écran, enregistrements et documents partagés.

L'export d'un workflow n'inclut généralement pas l'identifiant lui-même, mais une clé écrite dans les paramètres d'un nœud suit le JSON. Avant de partager un workflow, recherchez sk- et les préfixes de clés courants.

4. Variables d'environnement : pour la configuration, pas pour les secrets

n8n auto-hébergé utilise des variables d'environnement pour le port, la base, l'adresse de webhook, etc. Les valeurs sensibles comme N8N_ENCRYPTION_KEY ou le mot de passe de base doivent aussi être injectées par variable d'environnement ou gestionnaire de secrets, jamais écrites dans un fichier Compose commité dans Git. Certaines variables acceptent le suffixe _FILE pour lire la valeur depuis un fichier séparé.

Une variable d'environnement n'est cependant pas un coffre-fort. La documentation de n8n indique clairement qu'elles ne sont pas protégées et peuvent être exposées aux utilisateurs ; diffuser des identifiants en masse via CREDENTIALS_OVERWRITE_DATA n'est donc pas recommandé. Préférez un point de terminaison d'écrasement authentifié.

Si des utilisateurs métier peuvent éditer des workflows, activez N8N_BLOCK_ENV_ACCESS_IN_NODE=true pour empêcher les expressions et nœuds Code de lire les variables. La valeur par défaut est false et un redémarrage est nécessaire après modification. Notez aussi que l'historique d'exécution conserve entrées et sorties des nœuds : anonymisez les champs sensibles avant n8n ou réduisez la conservation avec EXECUTIONS_DATA_MAX_AGE.

5. Clé de chiffrement : la perdre rend tous les identifiants illisibles

Au premier démarrage, n8n génère une clé de chiffrement dans ~/.n8n et l'utilise pour chiffrer les identifiants écrits en base. Une valeur personnalisée peut être fournie via N8N_ENCRYPTION_KEY. La documentation précise que la perte de cette clé rend tous les identifiants enregistrés illisibles.

La sauvegarde doit donc être appariée : base de données et clé de chiffrement stockées séparément, avec des accès distincts. Sauvegarder seulement la base ne suffit pas après restauration sans la clé d'origine ; sauvegarder seulement la clé ne sert à rien si la base est perdue.

En mode queue, l'instance principale et tous les workers doivent partager le même N8N_ENCRYPTION_KEY, sinon les workers ne peuvent pas déchiffrer les identifiants écrits par le principal. Inscrivez ce point dans la checklist de déploiement avant toute montée en charge.

Depuis n8n 3.0, la rotation de la clé de chiffrement des données est prise en charge par défaut ; en 2.x, activez manuellement N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true et gardez la même valeur sur tous les nœuds. Sauvegardez toute la base avant de tourner ; la documentation déconseille aussi de revenir à une ancienne version après activation du nouveau format. L'entrée se trouve dans Settings > Data Encryption Keys.

6. Rotation et moindre privilège

La gestion des clés n'est pas un réglage unique : c'est une réduction continue des droits.

  • Par environnement : clés distinctes pour développement, test et production ; la clé de production ne réside pas sur un poste de développement.
  • Par projet : une clé par projet, avec suivi séparé de l'usage et du quota.
  • Par personne : une clé par personne, révoquée individuellement au départ, sans clé partagée par tous.
  • Expiration courte : date d'expiration pour les clés API publiques ; rotation régulière aussi pour les clés de modèles.
  • Créer avant de supprimer : lors d'une rotation, créer la nouvelle clé, mettre à jour l'appelant, valider, puis révoquer l'ancienne.
  • Moindre privilège : en Enterprise, ne cocher que les scopes nécessaires ; pour les rôles de projet, n'accorder que le requis.
  • Limiter l'usage : certains identifiants basés sur des API web permettent de restreindre les domaines HTTP appelés, réduisant le risque de réutilisation de la clé ailleurs.
  • Audit : conserver la création, l'usage et la suppression des clés, et alerter sur toute consommation anormale.

7. Rôles d'équipe et partage des identifiants

Les rôles d'instance n8n incluent Owner, Admin et Member ; projets et identifiants peuvent être isolés par projet. En Community Edition, les identifiants sont dans l'espace personnel ; les versions avec projets permettent de les placer dans un projet pour ses membres. Les rôles personnalisés et les permissions fines relèvent de l'édition Enterprise ; le périmètre exact figure dans la documentation.

Recommandations :

  1. Gardez peu d'Owner ; utilisez Admin ou Member au quotidien.
  2. Placez les workflows métier et leurs identifiants dans un projet, pas dans l'espace personnel.
  3. Nommez les identifiants « service-environnement-usage », par exemple « passerelle-production-resume-support ».
  4. Ne partagez pas les comptes de connexion et n'envoyez pas votre clé personnelle à un collègue.
  5. Activez MFA, imposez HTTPS en production et réglez N8N_SECURE_COOKIE=true.
  6. Utilisez un task runner externe en production ; la documentation marque le mode internal comme déconseillé et l'abandonne depuis 3.0.

L'édition Enterprise permet aussi un stockage de clés externe, en référençant des valeurs de 1Password Connect, AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager, HashiCorp Vault ou Infisical dans les champs d'identifiant. La référence n'est résolue que dans ce champ et n'apparaît pas dans les autres expressions du workflow.

8. Dépannage courant

Symptôme Cause possible Traitement
Identifiant indéchiffrable N8N_ENCRYPTION_KEY changée ou ancienne base restaurée Rétablir l'ancienne clé ; restaurer la sauvegarde associée
API publique 401 X-N8N-API-KEY absent ou expiré Recréer la clé, vérifier l'en-tête
API publique 403 Scopes Enterprise insuffisants Ajouter les scopes nécessaires comme workflow:read
Requête modèle 401 Clé erronée, expirée ou identifiant non sélectionné Ressaisir la clé, vérifier la liaison au nœud
Variable d'environnement illisible Variable non transmise au conteneur ou accès au nœud désactivé Vérifier l'environnement Compose et N8N_BLOCK_ENV_ACCESS_IN_NODE
Worker en échec de déchiffrement Clé différente entre worker et instance principale Unifier N8N_ENCRYPTION_KEY puis redémarrer

Commencez le diagnostic par « qu'est-ce qui a changé récemment » : changement de clé, d'URL de base, de version ou migration de base sont les quatre causes les plus fréquentes. Ne modifiez qu'une variable à la fois et validez immédiatement avec une requête minimale.

Questions fréquentes

La clé API n8n et la clé API OpenAI sont-elles la même chose ?

Non. La clé API n8n sert à appeler l'API REST de n8n, avec l'en-tête X-N8N-API-KEY ; la clé compatible OpenAI sert à appeler le modèle, stockée dans un identifiant et envoyée en Bearer par le nœud.

La clé API publique n8n prend-elle en charge des permissions ?

L'édition Enterprise prend en charge les Scopes, limitables à des ressources et actions précises ; il est recommandé de n'accorder que le nécessaire. Hors Enterprise, une clé dispose par défaut d'un accès complet aux ressources du compte : séparez par personne et usage, et fixez une expiration.

Que se passe-t-il si l'on modifie N8N_ENCRYPTION_KEY ?

Les identifiants déjà chiffrés deviennent généralement indéchiffrables. Fixez la valeur dès le premier déploiement et sauvegardez-la ; pour la changer, évaluez d'abord la rotation de clé prévue par l'outil plutôt que de modifier directement la variable.

Peut-on mettre la clé dans une variable d'environnement pour les workflows ?

C'est possible mais déconseillé. La documentation indique que les variables d'environnement ne sont pas protégées et peuvent être exposées. Préférez les identifiants ou un stockage de clés externe ; si une variable est indispensable, activez au moins N8N_BLOCK_ENV_ACCESS_IN_NODE et limitez l'accès à l'instance.

Peut-on partager une clé de modèle dans l'équipe ?

Ce n'est pas recommandé. Une clé partagée ne permet pas de distinguer les usages, une fuite affecte tout le monde et la révocation individuelle est impossible. Séparez par projet, environnement ou personne, et utilisez les quotas et rapports d'usage d'une passerelle pour mieux contrôler coût et sécurité.

Pour aller plus loin

Retenez la règle en une phrase : la clé API publique gère l'instance, la clé de modèle gère les appels, la clé de chiffrement gère la base. Stockez-les séparément, renouvelez-les séparément, et ajoutez rôles de projet, expiration et audit pour une configuration complète. Pour un point d'entrée et une gestion d'usage unifiés, inscrivez-vous à ZSQH AI Gateway ; modèles et prix sont sur la page tarifs des modèles.

Lectures associées :