Clé d’API (HTTP)

Une clé, un jeton Bearer ou un couple identifiant/mot de passe, présenté par le nœud « Requête HTTP ».

Une connexion par clé d'API conserve un secret que le nœud Requête HTTP présente à un service extérieur : une clé d'API dans un en-tête, un jeton Bearer, un identifiant et un mot de passe, ou une clé passée en paramètre d'URL. C'est le moyen d'appeler n'importe quelle API REST qui n'a pas d'intégration dédiée.

Le secret est chiffré dès l'enregistrement et n'en ressort jamais : ni l'API, ni l'écran Connexions, ni le graphe d'un workflow ne peuvent le relire. Un workflow ne porte que l'identifiant de la connexion ; le serveur applique le secret à la requête au moment de l'appel, sous le nœud, si bien que sa valeur n'apparaît jamais dans les données d'étape, le détail d'exécution ou les journaux.

En bref

• Identifiant : http_api_key
• Famille : Service
• Configurée par : Un membre (personnelle) ou un administrateur (partagée avec l’organisation)
• Authentification : Clé d’API ou jeton
• Type de credential : http_generic

Avant de commencer

• Le secret lui-même, créé dans la console du service extérieur, et la façon dont ce service attend de le recevoir (quel en-tête, quel nom de paramètre).
• Choisir la portée. Une connexion Personnelle n'est visible et utilisable que par vous. Une connexion Organisation sert à toute l'organisation, mais seul un administrateur peut la créer, la renommer ou la supprimer.
• Une clé de chiffrement (ENCRYPTION_KEY) configurée sur l'instance ; sans elle, aucun secret ne peut être stocké. Voir les variables d'environnement.

Les quatre formes

Choisissez la forme que documente l'API extérieure. Chacune a ses champs, et le serveur l'applique ainsi :

Forme (telle qu'affichée)	Champs	Envoyée comme
Clé d'API (en-tête)	Nom de l'en-tête (suggéré : X-API-Key), Valeur	un en-tête <Nom de l'en-tête>: <Valeur>
Jeton Bearer	Jeton	Authorization: Bearer <Jeton>
Identifiant et mot de passe	Identifiant, Mot de passe	Authorization: Basic … (authentification HTTP Basic, identifiant et mot de passe encodés en base64)
Paramètre d'URL	Nom du paramètre (suggéré : api_key), Valeur	un paramètre ?<Nom du paramètre>=<Valeur> ajouté à l'URL de la requête

Paramètre d'URL

Une clé passée dans l'URL apparaît dans les journaux du service appelé, et dans ceux de tout proxy sur le chemin. N'utilisez Paramètre d'URL que si l'API n'offre rien d'autre.

Limites : un nom de 1 à 80 caractères ; des noms d'en-tête et de paramètre jusqu'à 128 caractères ; des secrets jusqu'à 4 096 caractères ; des identifiants jusqu'à 256 caractères.

Ajouter la connexion

1. Ouvrez Connexions, cliquez sur Ajouter une connexion, puis sur Connecter sur la carte Clé d'API (HTTP). Le formulaire Nouvelle clé d'API s'ouvre.
2. Nom — ce que vous lirez dans le sélecteur d'un nœud, par exemple « API facturation — production ».
3. Portée — Personnelle ou Organisation. L'option Organisation n'est proposée qu'aux administrateurs.
4. Forme — l'une des quatre formes ci-dessus, puis remplissez ses champs. Les champs secrets sont masqués et ne sont plus jamais réaffichés après la création.
5. Cliquez sur Créer la connexion.

La connexion apparaît alors dans la famille Services de Connexions, avec son nom, sa forme et sa portée. Ce type de connexion n'a pas de bouton de test : la première exécution du nœud Requête HTTP en tient lieu.

L'utiliser dans un nœud

Dans le nœud Requête HTTP, choisissez la connexion dans le champ Authentification. Il est facultatif : laissez-le vide pour une API publique.

• La connexion l'emporte sur un en-tête du même nom saisi à la main dans En-têtes : choisir une connexion est l'intention la plus explicite.
• À chaque requête, le serveur vérifie que la connexion existe encore, qu'elle est active, et qu'elle est la vôtre ou celle de l'organisation. Sinon, l'étape échoue définitivement plutôt que de partir sans authentification.
• Le champ Authentification ne peut pas contenir d'expression {{ }} : une connexion n'est jamais choisie par le contenu d'un mail.
• Quand une étape tourne pendant un essai, le secret n'est pas déchiffré ; le détail d'exécution se contente de nommer la connexion qui aurait été utilisée.

Renommer, remplacer ou supprimer

• Renommer — le bouton Renommer sur la ligne de la connexion. Seul le nom change ; le secret est conservé.
• Remplacer le secret — l'écran ne modifie pas un secret : supprimez la connexion et créez-en une nouvelle, puis sélectionnez-la de nouveau dans les nœuds qui l'utilisaient. Par l'API, PUT /api/v1/credentials/:id avec un objet data remplace le secret en entier (tous les champs de sa forme doivent être renvoyés).
• Supprimer — le bouton Supprimer, puis confirmez. Le secret est effacé définitivement. La suppression est refusée tant qu'un workflow publié utilise la connexion : l'écran liste les workflows concernés. Mettez-les hors ligne, ou faites-les pointer vers une autre connexion, puis supprimez.

Seul un administrateur peut renommer, remplacer ou supprimer une connexion d'organisation.

Protections réseau

Le nœud Requête HTTP n'atteint que l'internet public. Quelle que soit la connexion, le serveur refuse :

• tout schéma autre que http et https, et tout port autre que 80 et 443 ;
• les URL qui embarquent un identifiant ou un mot de passe (https://user:pass@hote/) ;
• les adresses privées, de bouclage, lien-local, partagées (CGNAT), multicast et réservées, y compris l'adresse de métadonnées cloud 169.254.169.254 — en IPv4 comme en IPv6. Le contrôle porte sur l'adresse réellement connectée, ce qui déjoue les astuces DNS qui font pointer un nom public vers une adresse interne.

Les redirections sont suivies à la main, jusqu'à 5, et chaque saut repasse par les mêmes contrôles. Quand une redirection mène vers un autre hôte, les en-têtes Authorization, Cookie et Proxy-Authorization ne lui sont pas transmis.

Une requête refusée fait échouer l'étape définitivement avec le code http_blocked ; la retenter ne la rendrait pas licite.

Erreurs fréquentes

Code ou message	Cause	Que faire
credential.admin_required — Seul un administrateur gère une connexion d'organisation.	Un non-administrateur a voulu créer, renommer ou supprimer une connexion Organisation.	Demandez à un administrateur, ou créez une connexion Personnelle.
credential.in_use — Utilisée par un workflow publié : mettez-le hors ligne ou changez sa connexion avant de supprimer.	Un workflow publié référence la connexion.	Mettez les workflows listés hors ligne ou changez leur connexion, puis supprimez.
credential.not_found — Cette connexion n'existe pas (ou plus).	Supprimée, ou elle appartient à un autre membre.	Rechargez la page ; recréez la connexion si besoin.
credential.bad_request	Un champ manque, est trop long, ou n'appartient pas à la forme choisie.	Corrigez le formulaire.
credential.encryption_disabled — L'instance ne peut pas stocker de secret : la clé de chiffrement est absente.	ENCRYPTION_KEY n'est pas configurée.	Demandez à l'administrateur de l'instance de la configurer.
node_invalid_param — the configured credential cannot be used	À l'exécution, la connexion choisie dans le nœud a été supprimée, n'est plus active, ou est une connexion personnelle d'un autre membre.	Choisissez une connexion valide dans le champ Authentification du nœud et republiez.
http_blocked	L'URL, le port ou l'adresse résolue est refusé par les protections réseau.	Appelez une adresse publique sur le port 80 ou 443.
http_error_status — La réponse HTTP porte un statut d'erreur.	Avec Échouer sur une réponse d'erreur activé (le défaut), le service extérieur a répondu par un statut de 400 ou plus — par exemple 401 ou 403 quand il refuse la clé.	Vérifiez le secret, la forme, et le nom d'en-tête ou de paramètre attendu par le service.

Nœuds qui utilisent cette connexion

• Requête HTTP — http.request