Connecter une API à n8n : guide pratique avec exemples

• Comprendre les bases des API REST pour n8n
• Configurer l’authentification API dans n8n
• Utiliser le nœud HTTP Request dans vos workflows
• Gérer la pagination et les limites de taux API
• Déboguer les erreurs API dans n8n

Connecter une API à n8n transforme votre plateforme d’automatisation en hub universel capable de dialoguer avec n’importe quel service web. Que vous souhaitiez récupérer des données depuis un CRM propriétaire, synchroniser des commandes avec un ERP, ou déclencher des actions sur une API métier, le nœud HTTP Request de n8n devient votre outil principal. Ce guide vous montre comment configurer les quatre types d’authentification API les plus courants, construire des requêtes robustes, gérer la pagination et diagnostiquer les erreurs — avec des exemples concrets pour chaque cas.

Avant de connecter votre première API, vous devez maîtriser les fondamentaux des workflow n8n guide complet. Une fois cette base acquise, les connexions API deviennent un jeu de construction logique.

Comprendre les bases des API REST pour n8n

Une API REST fonctionne sur le protocole HTTP et expose des endpoints — des URLs spécifiques qui représentent des ressources. Chaque requête utilise une méthode HTTP qui définit l’action : GET pour récupérer des données, POST pour créer une ressource, PUT ou PATCH pour modifier, DELETE pour supprimer.

Les endpoints suivent généralement une structure logique. L’API d’un système de gestion de clients expose par exemple /api/v1/clients pour lister tous les clients, /api/v1/clients/123 pour récupérer le client avec l’ID 123, et /api/v1/clients/123/commandes pour ses commandes.

Chaque requête inclut des headers — des métadonnées qui précisent le format attendu, l’authentification, ou le type de contenu envoyé. Le header Content-Type: application/json indique que le body de la requête contient du JSON. Le header Accept: application/json précise que vous attendez une réponse JSON.

Le body d’une requête POST ou PUT contient les données à créer ou modifier, généralement au format JSON. Une requête POST vers /api/v1/clients avec un body {"nom": "Dupont", "email": "[email protected]"} crée un nouveau client.

Les codes de réponse HTTP signalent le résultat : 200 pour un succès, 201 pour une création réussie, 400 pour une requête mal formée, 401 pour un problème d’authentification, 404 pour une ressource introuvable, 429 pour un dépassement de quota, 500 pour une erreur serveur. Connaître ces codes vous permet de construire une logique de gestion d’erreur efficace dans vos workflows.

La documentation de l’API REST détaille ces concepts fondamentaux. Chaque API que vous connectez à n8n fournit sa propre documentation — lisez-la toujours avant de commencer.

Configurer l’authentification API dans n8n

L’authentification API sécurise l’accès aux données. n8n supporte quatre méthodes principales, chacune adaptée à un contexte différent.

API Key

La clé API est la méthode la plus simple. Le service vous fournit une chaîne de caractères unique que vous incluez dans chaque requête, soit dans un header, soit dans un paramètre d’URL.

Dans n8n, créez un credential de type « Header Auth » si la clé se place dans un header personnalisé. Nommez le header selon la documentation de l’API — souvent X-API-Key ou Authorization. Collez votre clé dans le champ « Value ».

Si l’API attend la clé dans l’URL comme paramètre de requête, ajoutez-la directement dans le nœud HTTP Request sous « Query Parameters » : api_key comme nom, votre clé comme valeur.

Exemple concret : l’API OpenWeatherMap utilise ?appid=VOTRE_CLE dans l’URL. Configurez un paramètre de requête appid avec votre clé, et chaque appel l’inclura automatiquement.

OAuth2

OAuth2 délègue l’authentification à un serveur d’autorisation. L’utilisateur se connecte une fois, le service délivre un token d’accès temporaire que n8n renouvelle automatiquement.

Dans n8n, créez un credential « OAuth2 API ». Renseignez l’Authorization URL, l’Access Token URL, le Client ID et le Client Secret fournis par le service. Définissez le Scope — les permissions demandées — selon la documentation.

Cliquez sur « Connect my account ». n8n ouvre une fenêtre d’autorisation. Connectez-vous, acceptez les permissions, et n8n stocke le token. Vous n’intervenez plus : n8n gère le renouvellement.

Exemple concret : connecter l’API Google Sheets via OAuth2 permet à vos workflows de lire et modifier des feuilles de calcul sans stocker de mot de passe. Le token expire après une heure, mais n8n le renouvelle en arrière-plan.

Bearer Token / JWT

Le Bearer token est un jeton d’accès que vous obtenez via un endpoint de login, puis incluez dans le header Authorization: Bearer VOTRE_TOKEN de chaque requête suivante. JWT (JSON Web Token) est un format de token signé cryptographiquement.

Dans n8n, si le token ne change jamais, créez un credential « Header Auth » avec le header Authorization et la valeur Bearer VOTRE_TOKEN.

Si vous devez obtenir le token dynamiquement, construisez un workflow en deux étapes : un premier nœud HTTP Request POST vers l’endpoint de login avec vos identifiants, qui retourne le token, puis un second nœud qui utilise ce token via une expression {{ $json.token }} dans le header Authorization.

Exemple concret : l’API Stripe utilise un Bearer token. Créez un credential avec Authorization: Bearer sk_test_VOTRE_CLE_SECRETE et chaque requête s’authentifie automatiquement.

Basic Auth

Basic Auth envoie un nom d’utilisateur et un mot de passe encodés en Base64 dans le header Authorization: Basic ENCODED_CREDENTIALS. C’est simple mais moins sécurisé — réservez-le aux APIs internes ou protégées par HTTPS.

Dans n8n, créez un credential « Basic Auth ». Entrez le nom d’utilisateur et le mot de passe. n8n encode et envoie le header automatiquement.

Exemple concret : certaines APIs de monitoring ou d’administration système utilisent Basic Auth. Configurez le credential une fois, et tous vos workflows qui appellent cette API héritent de l’authentification.

Pour approfondir la sécurisation de vos workflows, consultez le guide sur securiser workflows n8n.

Utiliser le nœud HTTP Request dans vos workflows

Le nœud HTTP Request est l’outil universel pour connecter n’importe quelle API. Ajoutez-le à votre canvas, configurez la méthode HTTP, l’URL, les credentials, les headers, les paramètres et le body.

Commencez par la méthode : GET pour récupérer des données, POST pour créer, PUT ou PATCH pour modifier, DELETE pour supprimer. Collez l’URL complète de l’endpoint dans le champ « URL ». Si l’URL contient des variables, utilisez des expressions : https://api.exemple.com/clients/{{ $json.client_id }} insère dynamiquement l’ID du client depuis les données du nœud précédent.

Sélectionnez le credential d’authentification que vous avez créé. Si l’API n’a pas de nœud natif dans n8n, le nœud HTTP Request avec le bon credential remplace n’importe quelle intégration préfabriquée.

Ajoutez des headers personnalisés si nécessaire. Content-Type: application/json est requis pour envoyer du JSON. Accept: application/json demande une réponse JSON. Certains services exigent des headers spécifiques — lisez la documentation.

Configurez les paramètres de requête (query parameters) pour les filtres, la pagination, ou les options. Une requête GET vers /api/v1/produits?categorie=electronique&limite=50 se configure avec deux paramètres : categorie = electronique, limite = 50.

Pour POST ou PUT, activez « Send Body » et choisissez le format — généralement JSON. Construisez le body soit en mode « JSON » avec un objet structuré, soit en mode « Expression » pour insérer des données dynamiques : {"nom": "{{ $json.nom }}", "prix": {{ $json.prix }}}.

Les expressions n8n accèdent aux données des nœuds précédents. {{ $json.champ }} récupère un champ du nœud actuel. {{ $node["Nom du nœud"].json.champ }} récupère un champ d’un nœud spécifique. Les fonctions comme {{ $now.toISO() }} génèrent des timestamps.

Testez chaque requête avec le bouton « Execute Node ». n8n affiche la réponse, les headers retournés, et le code de statut. Inspectez le JSON retourné pour comprendre la structure des données — vous en aurez besoin pour les nœuds suivants.

Activez « Ignore SSL Issues » uniquement pour des tests en développement local. En production, une erreur SSL signale un problème de certificat — ne la masquez pas.

Pour des cas d’usage concrets, explorez les exemples workflows n8n entreprise qui montrent comment chaîner plusieurs appels API dans un même workflow.

Gérer la pagination et les limites de taux API

La plupart des APIs limitent le nombre de résultats par requête. Une API de gestion de contacts retourne 100 contacts maximum par appel, même si vous en avez 5000. Vous devez paginer — récupérer les résultats page par page.

Deux méthodes de pagination dominent. La pagination par offset utilise des paramètres limit et offset : la première requête demande ?limit=100&offset=0, la seconde ?limit=100&offset=100, et ainsi de suite. La pagination par curseur retourne un token dans la réponse, que vous incluez dans la requête suivante : ?cursor=TOKEN.

Dans n8n, utilisez un nœud Loop Over Items combiné avec un nœud Function pour construire les requêtes successives. Le nœud Function calcule l’offset ou extrait le curseur de la réponse précédente, le nœud HTTP Request appelle l’API, et la boucle continue jusqu’à ce que la réponse soit vide.

Exemple concret : pour récupérer 5000 contacts avec une limite de 100 par requête, configurez une boucle qui incrémente l’offset de 100 à chaque itération, appelle l’API, et agrège les résultats dans un tableau.

Les limites de taux (rate limits) protègent les APIs contre la surcharge. Une API autorise par exemple 100 requêtes par minute. Si vous dépassez ce quota, elle retourne un code 429 et un header Retry-After indiquant combien de secondes attendre.

Dans n8n, activez « Retry On Fail » dans les paramètres du nœud HTTP Request. Configurez le nombre de tentatives et le délai entre chaque tentative. Si l’API retourne 429, n8n attend et réessaie automatiquement.

Pour des workflows qui appellent l’API fréquemment, ajoutez un nœud Wait entre les appels. Un délai de 1 seconde entre chaque requête garantit que vous restez sous la limite de 60 requêtes par minute.

Certaines APIs incluent des headers X-RateLimit-Remaining et X-RateLimit-Reset dans chaque réponse. Utilisez un nœud Function pour lire ces headers et ajuster dynamiquement le délai entre les appels.

Stockez les tokens de pagination et les compteurs de requêtes dans des variables de workflow ou dans une base de données externe si le workflow s’exécute sur plusieurs jours. Cela évite de recommencer depuis zéro en cas d’interruption.

Déboguer les erreurs API dans n8n

Chaque appel API peut échouer. Le débogage méthodique transforme une erreur opaque en solution claire.

Commencez par le code de statut HTTP. Un code 400 signale une requête mal formée — vérifiez le body JSON, les paramètres, et les headers requis. Un code 401 indique un problème d’authentification — vérifiez votre credential, le token, ou la clé API. Un code 403 signifie que vous êtes authentifié mais sans permission — vérifiez les scopes OAuth2 ou les droits de votre compte. Un code 404 indique que l’endpoint ou la ressource n’existe pas — vérifiez l’URL. Un code 429 signale un dépassement de quota — ajoutez des délais ou réduisez la fréquence. Un code 500 est une erreur serveur — le problème est côté API, pas dans votre workflow.

Lisez le message d’erreur retourné dans le body de la réponse. Les APIs bien conçues retournent un JSON explicite : {"error": "invalid_token", "message": "Le token a expiré"}. Ce message vous dit exactement quoi corriger.

Utilisez l’onglet « Executions » de n8n pour inspecter l’historique de chaque exécution. Cliquez sur une exécution échouée, ouvrez le nœud HTTP Request, et consultez les données d’entrée, la requête envoyée, et la réponse reçue. Comparez la requête construite par n8n avec la documentation de l’API — souvent, un header manquant ou un paramètre mal nommé explique l’échec.

Testez vos requêtes en dehors de n8n avec un outil comme Postman ou curl. Si la requête échoue aussi dans Postman, le problème vient de votre configuration API, pas de n8n. Si elle réussit dans Postman mais échoue dans n8n, comparez les headers, le body, et les paramètres envoyés — une différence subtile explique l’écart.

Activez « Always Output Data » dans les paramètres du nœud HTTP Request pour que n8n passe les données au nœud suivant même en cas d’erreur. Cela vous permet d’ajouter un nœud Function ou IF qui analyse l’erreur et décide de la suite — réessayer, notifier, ou arrêter.

Ajoutez des nœuds de logging — un nœud Function qui écrit dans la console ou envoie un message Slack avec les détails de l’erreur. En production, ces logs deviennent votre première source de diagnostic.

Pour les workflows complexes avec plusieurs appels API, isolez chaque appel dans un workflow séparé que vous testez individuellement. Une fois chaque appel validé, assemblez-les dans le workflow final. Cette approche modulaire réduit la surface d’erreur.

Comparez les capacités de n8n avec d’autres outils d’automatisation dans le guide n8n vs zapier make pour comprendre les forces et limites de chaque plateforme.

Connecter une API à n8n ne demande pas de compétences de développeur avancées — seulement de la rigueur et une lecture attentive de la documentation. Chaque API suit les mêmes principes : authentification, requête structurée, gestion des erreurs, pagination. Une fois ces mécaniques maîtrisées, vous transformez n8n en hub d’intégration universel qui dialogue avec n’importe quel service web, ouvrant des centaines de possibilités d’automatisation pour votre activité.