Gérer les credentials n8n via l'API REST : créer, supprimer, transférer

Vous provisionnez des instances n8n pour vos clients, vous dupliquez des workflows entre un environnement de dev et de la prod, ou vous voulez injecter des clés API depuis votre pipeline CI/CD ? Créer chaque credential à la main dans l'interface ne tient pas la route au-delà de deux ou trois instances. Bonne nouvelle : l'API publique REST de n8n permet de gérer les credentials par programme — les créer, les supprimer, les transférer entre projets. Avec une limite volontaire et saine : elle ne permet jamais de relire les secrets existants. Ce guide passe en revue les endpoints, un exemple complet en curl, et les cas d'usage où cette API change la donne.

Ce que l'API credentials permet (et ne permet pas)

L'API publique n8n est exposée sous https://votre-instance/api/v1 et s'authentifie avec le header X-N8N-API-KEY. Si vous n'avez pas encore de clé, suivez notre guide pour créer et sécuriser une clé API n8n. Côté credentials, les opérations disponibles sont :

• POST /api/v1/credentials : créer un credential (nom, type, données).
• GET /api/v1/credentials/schema/{credentialTypeName} : récupérer le schéma JSON d'un type de credential, c'est-à-dire la liste des champs attendus.
• DELETE /api/v1/credentials/{id} : supprimer un credential dont vous êtes propriétaire.
• PUT /api/v1/credentials/{id}/transfer : transférer un credential vers un autre projet (corps : {"destinationProjectId": "..."}).

Les versions récentes de n8n ajoutent des opérations de lecture et de mise à jour (lister les credentials, en modifier un existant), mais avec une constante absolue : la réponse ne contient jamais le champ data. Les secrets sont en écriture seule (write-only) dans le schéma OpenAPI officiel. Vous pouvez pousser une clé API dans n8n, jamais la relire.

Ce n'est pas un oubli, c'est de la sécurité by design : les credentials sont chiffrés au repos avec la clé d'instance (N8N_ENCRYPTION_KEY), et une clé API compromise ne doit pas suffire à exfiltrer tous les secrets de l'instance. Nous détaillons ce modèle dans notre article sur la sécurisation des credentials dans n8n.

Étape 1 : récupérer le schéma du type de credential

Avant de créer un credential, il faut connaître deux choses : le nom technique du type (credentialTypeName) et les champs qu'il attend. Le nom technique s'obtient facilement en exportant un workflow qui utilise déjà ce credential : il apparaît dans le JSON du node (githubApi, slackOAuth2Api, postgres…).

Le schéma, lui, se récupère par API :

curl -X GET \
  "https://votre-instance.exemple.com/api/v1/credentials/schema/freshdeskApi" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Réponse (exemple documenté par n8n pour freshdeskApi) :

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "apiKey": { "type": "string" },
    "domain": { "type": "string" }
  },
  "required": ["apiKey", "domain"]
}

Vous savez désormais exactement quoi envoyer. Ce mécanisme de découverte est précieux pour écrire des scripts de provisioning génériques : votre outil interroge le schéma, valide ses entrées, puis crée le credential.

Étape 2 : créer le credential avec POST /api/v1/credentials

La création se fait avec trois champs obligatoires : name (le libellé affiché dans l'interface), type (le nom technique du type) et data (l'objet contenant les secrets, conforme au schéma récupéré à l'étape 1) :

curl -X POST "https://votre-instance.exemple.com/api/v1/credentials" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Freshdesk — Client Acme",
    "type": "freshdeskApi",
    "data": {
      "apiKey": "votre-cle-freshdesk",
      "domain": "acme"
    }
  }'

La réponse renvoie l'id du credential créé, son nom, son type et les dates de création — mais pas data. Notez cet id : c'est lui que vous référencerez ensuite dans les workflows importés par API, ou que vous utiliserez pour supprimer ou transférer le credential. Sur les versions récentes, vous pouvez aussi passer un projectId pour créer directement le credential dans un projet donné plutôt que dans votre espace personnel.

Depuis n8n lui-même, la même requête se fait avec un node HTTP Request pointant vers votre seconde instance — pratique pour orchestrer le provisioning avec l'API REST n8n qui pilote vos workflows.

Supprimer et transférer un credential

La suppression est directe :

curl -X DELETE \
  "https://votre-instance.exemple.com/api/v1/credentials/vHxaz5UaCghVYl9C" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Le transfert entre projets utilise un PUT avec l'identifiant du projet de destination :

curl -X PUT \
  "https://votre-instance.exemple.com/api/v1/credentials/vHxaz5UaCghVYl9C/transfer" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destinationProjectId": "VmwOO9HeTEj20kxM"}'

Gardez en tête que les projets multiples relèvent des plans payants de n8n ; sur une instance communautaire, cette opération n'a pas d'objet.

Cas d'usage : quand l'API credentials devient indispensable

• Provisioning automatisé d'instances : vous déployez une instance n8n par client (marque blanche, agence) et un script crée à la volée les credentials SMTP, CRM et base de données du client au premier démarrage. Combiné à un déploiement scripté, l'onboarding passe de deux heures à deux minutes.
• Environnements dev / staging / prod : les workflows voyagent par Git, mais les secrets ne doivent jamais y figurer. Votre pipeline crée dans chaque environnement des credentials portant le même nom, pointant vers les bons systèmes — l'approche que nous recommandons dans notre guide des environnements dev et prod avec n8n.
• CI/CD : lors du déploiement, GitHub Actions injecte les secrets du coffre (GitHub Secrets, Vault) dans l'instance cible via POST /credentials, puis importe les workflows. Voyez notre guide pour valider les workflows n8n en CI avec GitHub Actions.
• Rotation des secrets : quand une clé tierce est régénérée, un workflow planifié met à jour le credential correspondant (ou le recrée) sur toutes vos instances, sans intervention manuelle.

Bonnes pratiques : l'API ne remplace pas l'hygiène des secrets

Le risque principal n'est pas dans l'API n8n, mais dans la façon dont vos scripts manipulent les secrets avant de les envoyer. Une étude de Meli, McNiece et Reaves présentée en 2019 au symposium NDSS (How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories) a montré que des milliers de secrets uniques (clés API, clés privées) fuitent chaque jour dans des dépôts GitHub publics, touchant plus de 100 000 dépôts. Dans le même esprit, Rahman, Parnin et Williams ont identifié en 2019 dans une étude ICSE sur 15 232 scripts d'infrastructure-as-code (The Seven Sins: Security Smells in Infrastructure as Code Scripts) que les credentials codés en dur figurent parmi les défauts de sécurité les plus répandus. Concrètement :

1. Jamais de secrets en clair dans vos scripts ou votre dépôt Git — même si vous versionnez vos workflows n8n avec Git, les secrets viennent d'un coffre (Vault, GitHub Secrets, variables d'environnement chiffrées).
2. Passez les valeurs par variables d'environnement au moment de l'exécution du script, comme le $N8N_API_KEY des exemples ci-dessus.
3. Une clé API n8n par usage, révocable indépendamment, et transmise uniquement en HTTPS.
4. Sauvegardez N8N_ENCRYPTION_KEY : sans elle, les credentials restaurés depuis une sauvegarde sont indéchiffrables.
5. Vérifiez les détails sur votre version : l'API publique évolue (lecture des métadonnées, mise à jour, projectId à la création) ; la référence exacte pour votre instance est le schéma OpenAPI accessible dans les paramètres de l'API, ou la documentation officielle docs.n8n.io.

En résumé

L'API publique n8n couvre l'essentiel du cycle de vie des credentials : découverte du schéma (GET /credentials/schema/{type}), création (POST /credentials), suppression (DELETE /credentials/{id}) et transfert entre projets (PUT /credentials/{id}/transfer), le tout authentifié par le header X-N8N-API-KEY. Elle ne permet volontairement jamais de relire les secrets stockés — le champ data est en écriture seule. C'est la brique qui rend possibles le provisioning multi-instances, la séparation dev/prod propre et l'injection de secrets en CI/CD. Le maillon faible reste vos scripts : secrets hors du code, coffre-fort en amont, et une clé API dédiée par usage.