La clé API n8n : créer, utiliser, sécuriser et révoquer l'accès à votre instance

Tapez « n8n api key » dans un moteur de recherche : vous trouverez surtout où cliquer, rarement ce que la clé permet vraiment ni comment la gérer sur la durée. C'est pourtant le point sensible : une clé API n8n donne un accès programmatique complet à votre instance — workflows, exécutions, credentials, utilisateurs selon l'édition. Ce guide couvre le cycle de vie entier de cette clé : la créer, comprendre sa portée exacte, l'utiliser proprement (header X-N8N-API-KEY), la stocker, la faire tourner, la révoquer — et couper l'API publique si vous ne vous en servez pas.

À quoi sert une clé API n8n

La clé API est la porte d'entrée de l'API publique de n8n, celle qui permet d'administrer l'instance par programme : exporter les workflows pour sauvegarde, les activer ou les désactiver en masse, consulter l'historique des exécutions, provisionner des credentials, et selon l'édition gérer les utilisateurs. Tout pipeline CI/CD ou script d'exploitation passe par elle.

Le pilotage de n8n par son API REST — endpoints, pagination, cas d'usage détaillés — a son guide dédié. Ici, on se concentre sur la clé elle-même : c'est elle qui concentre le risque.

Créer la clé : Settings → n8n API

1. Connectez-vous à votre instance avec le compte qui portera la clé (on y revient juste après, ce choix compte) ;
2. Ouvrez Settings, puis la section n8n API ;
3. Cliquez sur Create an API key. Selon la version, vous pouvez donner un libellé à la clé — faites-le systématiquement (« backup-nocturne », « ci-github ») — et définir une durée de validité ;
4. Copiez la clé immédiatement : elle n'est affichée qu'une seule fois. Si vous la perdez, il faudra en générer une nouvelle.

Destination du copier-coller : un gestionnaire de secrets (Vault, Bitwarden, le secret manager de votre cloud) ou une variable d'environnement côté serveur — jamais un fichier de notes, un canal Slack ou un commit.

La portée de la clé : elle agit en votre nom, sans nuance

C'est le point le plus mal compris. Une clé API n8n agit au nom du compte qui l'a créée, avec l'ensemble de ses droits : pas de granularité « lecture seule » ou « limitée à tel workflow » sur la plupart des instances — un seul niveau de permission, celui du compte. Une clé créée par un compte owner ou admin peut donc lire, modifier, supprimer ou désactiver tous les workflows, et manipuler les credentials. Sur une instance multi-utilisateurs, la façon la plus simple de limiter une clé est de la créer depuis un compte membre aux droits restreints — notre guide des utilisateurs et permissions sur n8n self-hosted détaille les rôles. Dans les autres cas, traitez-la comme un secret de niveau administrateur, parce que c'en est un.

Utiliser la clé : le header X-N8N-API-KEY

Toutes les requêtes vers l'API publique passent par le préfixe /api/v1 et portent la clé dans un header dédié, X-N8N-API-KEY. Le test le plus simple, depuis un terminal :

export N8N_API_KEY="votre-clé"  # en pratique : depuis votre gestionnaire de secrets

curl -s "https://n8n.exemple.fr/api/v1/workflows?active=true" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Une réponse JSON listant vos workflows actifs : la clé fonctionne. Une erreur 401 : clé absente, mal orthographiée ou révoquée.

Depuis un workflow n8n lui-même (oui, une instance peut s'auto-administrer), utilisez un node HTTP Request avec un credential Header Auth : nom du header X-N8N-API-KEY, valeur la clé. Le credential est chiffré en base, alors qu'une clé collée en dur dans le paramètre du node partirait en clair dans chaque export du workflow. Côté script, la clé vit dans une variable d'environnement : le code n'en connaît que le nom.

Self-hosted ou Cloud : qui a accès à l'API ?

Sur une instance self-hosted, l'API publique est incluse, sans surcoût ni restriction. Sur n8n Cloud, sa disponibilité dépend du plan souscrit — les conditions évoluant, vérifiez la présence de la section n8n API dans vos Settings et la grille tarifaire en vigueur. Si l'API est un besoin structurant (CI/CD, backup automatisé), intégrez ce critère dans votre choix d'offre dès le départ.

Sécuriser : une clé par usage, rotation, révocation

Les fuites de clés ne sont pas un risque théorique. L'étude de Michael Meli, Matthew McNiece et Bradley Reaves, « How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories », présentée à NDSS en 2019 (voir sur Google Scholar), a scanné les commits publics de GitHub en temps réel pendant près de six mois : des milliers de secrets uniques — clés API, tokens, clés cryptographiques — fuitent chaque jour, et plus de 100 000 dépôts en contenaient. La cause dominante n'est pas l'attaque sophistiquée : c'est le commit ordinaire d'un fichier qui n'aurait jamais dû être versionné.

Appliqué à n8n, cela donne quatre règles :

• Une clé par usage. Une pour le backup, une pour le monitoring, une pour la CI. Le jour où l'une fuite, vous la révoquez sans casser le reste — et son libellé dit ce qui est exposé ;
• Stockage hors du code. Gestionnaire de secrets ou variable d'environnement, jamais en dur dans un script ni dans un paramètre de node d'un workflow que vous versionnez dans Git — l'export JSON embarque les valeurs des paramètres. Mêmes réflexes que pour la sécurisation des credentials API ;
• Rotation planifiée. Créez la nouvelle clé, basculez les consommateurs, supprimez l'ancienne. À faire à date fixe pour les clés permanentes, et immédiatement au départ d'un membre qui y avait accès ;
• Révocation immédiate au moindre doute. Settings → n8n API → suppression : l'effet est instantané. Révoquez d'abord, enquêtez ensuite.

Vous n'utilisez pas l'API ? Désactivez-la

Une porte que personne n'emprunte n'a pas besoin d'exister. Si rien n'appelle votre API publique — ni script, ni CI, ni outil externe —, coupez-la au niveau de l'instance :

N8N_PUBLIC_API_DISABLED=true

L'interface web et les webhooks continuent de fonctionner normalement ; seuls les endpoints /api/v1 disparaissent. C'est une réduction de surface d'attaque gratuite — réactivable en trente secondes le jour où un vrai besoin apparaît.

Clé API, credentials, webhook : trois objets, trois rôles

La confusion est fréquente et coûte cher quand elle expose le mauvais niveau de privilège :

• La clé API n8n authentifie un appel vers l'administration de l'instance. Portée maximale, à protéger comme un accès root ;
• Les credentials stockent les secrets que vos workflows utilisent vers des services tiers (Google, Stripe, OpenAI…). Chiffrés en base, jamais inclus dans les exports de workflows ;
• Un webhook est une porte d'entrée vers un seul workflow : sa portée se limite à ce que ce workflow fait, et son authentification se configure node par node — notre guide complet des webhooks couvre le sujet.

Règle pratique : si un système tiers doit déclencher un traitement, donnez-lui un webhook. La clé API ne sort jamais du cercle des outils d'administration.

Trois cas d'usage qui justifient une clé

• Backup nocturne vers Git. Un script (ou un workflow planifié) appelle /api/v1/workflows, écrit un fichier JSON par workflow et committe les changements. Le format est le même que l'export manuel de workflows, mais sans dépendre de personne. Clé dédiée « backup », créée depuis un compte aux droits minimaux ;
• Déploiement dev → prod. Le pipeline récupère le workflow sur l'instance de dev, remappe les identifiants de credentials, le pousse sur la prod et l'active. Deux clés distinctes, une par instance, stockées dans les secrets de la CI — voir nos guides des environnements dev et prod et de la validation des workflows n8n en CI avec GitHub Actions ;
• Inventaire des workflows actifs. Un appel filtré sur active=true alimente un tableau de bord ou un rapport hebdomadaire : ce qui tourne réellement, par qui, depuis quand. Sur une instance qui a grossi organiquement, c'est souvent la première surprise.

En résumé

La clé API n8n se crée en trente secondes dans Settings → n8n API, mais elle engage bien plus : elle agit au nom du compte qui l'a créée, avec un seul niveau de permission, et ouvre l'administration complète de l'instance via le header X-N8N-API-KEY. Le cycle de vie sain tient en une phrase : une clé nommée par usage, stockée dans un gestionnaire de secrets ou une variable d'environnement, tournée à date fixe, révoquée sans hésiter — et une API désactivée (N8N_PUBLIC_API_DISABLED=true) tant que personne ne s'en sert.