Clé API : définition, types et bonnes pratiques
Une clé API est un secret utilisé pour authentifier ou identifier des appels vers une API. n8n indique que son API utilise des clés API pour authentifier les appels. Selon le fournisseur, la clé peut être envoyée dans un en-tête Authorization avec le préfixe Bearer, dans X-API-Key ou dans un champ propriétaire. Une clé dans une URL risque de fuiter via les journaux.
Types de clés
On rencontre des clés serveur, des clés publiques limitées, des jetons personnels, des tokens d’application et des clés par environnement. Une clé de production ne doit pas servir aux tests. Une clé côté navigateur doit être très limitée, car elle peut être vue.
Bon usage
- Stocker la clé dans un gestionnaire de secrets ou variable d’environnement.
- Limiter les permissions au besoin réel.
- Faire tourner les clés régulièrement.
- Ne jamais la copier dans un article, un ticket public ou un dépôt Git.
Erreur classique
Une clé API prouve rarement l’identité d’un utilisateur final. Si vous devez autoriser un utilisateur à accéder à ses données, OAuth ou OpenID Connect seront souvent plus adaptés. La clé API sert surtout à une application, un service ou une intégration.
Rotation et incident
Prévoyez la rotation avant l’incident. Une clé doit pouvoir être remplacée sans modifier le code source : variable d’environnement, secret manager, réglage du connecteur ou coffre d’équipe. Si une clé fuit, la bonne séquence est courte : révoquer, créer une nouvelle clé, redéployer, puis chercher où l’ancienne clé a été exposée. Ne commencez pas par nettoyer le dépôt si la clé compromise fonctionne encore.
Indice de mauvais design
Si une seule clé donne accès à toutes les actions d’un compte, limitez-la côté fournisseur si possible. Une intégration qui lit seulement des statistiques ne devrait pas pouvoir supprimer des données. La clé doit correspondre au périmètre réel du workflow.
Headers fréquents
Les formes courantes sont Authorization: Bearer xxx, X-API-Key: xxx ou un header nommé par le fournisseur. Suivez toujours la documentation officielle : changer le header pour “faire propre” ne fonctionne pas si l’API attend un nom précis.
À journaliser sans fuite
Dans les logs, indiquez seulement que la clé est présente ou absente, jamais sa valeur. Pour diagnostiquer, loguez le nom du fournisseur, le statut HTTP et l’identifiant de requête retourné par l’API. Cela suffit souvent à corriger sans exposer le secret.
Le nom de l’en-tête dépend du service
L’API de n8n utilise X-N8N-API-KEY. Copier Authorization: Bearer d’un autre fournisseur ne fonctionnera donc pas nécessairement. Le nom du champ, le préfixe éventuel et les permissions viennent de la documentation de l’API, pas d’une convention universelle.
Un exemple pédagogique peut montrer X-N8N-API-KEY: VOTRE_CLE, mais jamais une vraie valeur. Les fichiers de configuration, historiques du terminal, exports de workflow et outils de capture réseau peuvent conserver cette valeur même si l’interface l’affiche avec des points.
Réagir à une fuite
Retirer la clé d’un message ne la révoque pas. Désactivez-la chez le fournisseur, créez une nouvelle clé limitée puis remplacez-la dans les intégrations concernées. Consultez les journaux d’utilisation pour identifier d’éventuels appels inattendus. Quand le service le permet, préparez une rotation avec une courte période de coexistence plutôt qu’une coupure non maîtrisée de tous les workflows.