Les autorisations des clés API déterminent ce qu'une clé divulguée peut compromettre. Dans un outil de liens, le choix sûr par défaut est une clé liée à un seul espace de travail, limitée au rôle le moins élevé qui suffit à la tâche, stockée sous forme de hachage avec secret additionnel, soumise à sa propre limite de débit et assortie d'une expiration. Une clé qui ne crée que des liens n'a aucune raison d'accéder aux webhooks, aux membres ou à la facturation, et elle ne doit jamais ouvrir un endpoint d'administration. C'est le principe du moindre privilège, qui repose en grande partie sur les choix faits pendant les trente secondes nécessaires à la création de la clé.
J'ai étudié beaucoup de configurations d'automatisation au cours de l'année écoulée, et le scénario se répète : quelqu'un colle sa clé toute-puissante dans n8n un vendredi après-midi, tout fonctionne, puis plus personne n'y pense jusqu'à son départ ou jusqu'à ce que l'export du workflow arrive sur un espace de stockage partagé. Le reste de cet article explique comment fonctionnent les portées et les rôles des clés API dans un produit de liens courts, ce que chaque rôle permet réellement de faire et comment transmettre une clé à un outil d'automatisation sans lui confier l'espace de travail.
Cet article complète notre checklist de sécurité d'un raccourcisseur d'URL, qui couvre l'analyse, la signature des webhooks et les journaux d'audit sur l'ensemble de la plateforme. Ici, nous nous concentrons sur la clé elle-même.
Ce que signifient les autorisations des clés API dans un outil de liens
L'API d'un outil de liens ne touche pas uniquement aux liens. Le même jeton qui crée go.example.com/spring-sale peut, selon ses autorisations, lire les statistiques de clics, ajouter un domaine personnalisé, inviter un membre ou enregistrer un webhook qui envoie chaque événement à un serveur externe. C'est ce dernier point qui m'inquiète. Un webhook est un flux permanent de données que la personne qui le crée peut diriger vers n'importe quel serveur, sans que personne dans votre équipe ne s'en aperçoive nécessairement pendant des semaines.
Les autorisations ont donc trois axes. Où la clé fonctionne-t-elle, c'est-à-dire dans quel compte ou espace de travail ? Que peut-elle y faire, lire, écrire ou administrer ? Et pendant combien de temps, à quelle vitesse ? La définition du moindre privilège donnée par le NIST revient à n'accorder que l'accès nécessaire à une tâche, et ces trois axes en font partie. Une clé en lecture seule qui n'expire jamais et n'a aucune limite de débit reste trop privilégiée dans le temps.
Clés API limitées à un espace de travail : une clé, un espace de travail
Dans Elido, chaque clé est créée dans un espace de travail et y reste. Si vous appelez avec elle les endpoints d'un autre espace de travail, vous obtenez une réponse 404, identique à celle d'un espace de travail inexistant. Une clé ne peut donc même pas confirmer l'existence d'autres espaces de travail.
C'est plus important qu'il n'y paraît. Les agences et les grandes équipes appartiennent souvent à cinq ou dix espaces de travail. Si une clé personnelle héritait de tout ce que son créateur peut atteindre, un seul jeton divulgué provenant d'un projet client ouvrirait l'accès à tous les clients. Les clés API limitées à un espace de travail réduisent la portée de l'incident à un seul espace de travail.
La clé est également plafonnée au rôle choisi lors de sa création et ne dépasse jamais le rôle actuel de son créateur. L'accès effectif correspond au niveau le plus bas des deux. Si l'administrateur qui a créé une clé est rétrogradé au rôle d'éditeur, la clé l'est aussi. Les autorisations personnalisées associées à ce membre sont également supprimées lorsque le rôle de la clé est le plus bas, car elles décrivent la personne et non la clé.
Clés API basées sur les rôles : ce que chaque rôle permet de faire
Les clés Elido utilisent les quatre mêmes rôles que les utilisateurs : lecteur, éditeur, administrateur et propriétaire. Vous en choisissez un lors de la création de la clé. Si vous ne le précisez pas, la clé prend par défaut le rôle d'éditeur, qui convient à la tâche d'automatisation habituelle consistant à créer des liens et à lire les statistiques sans accès à l'administration.
Voici ce que cela donne en pratique pour les éléments auxquels les intégrations accèdent généralement.
| Rôle | Liens et campagnes | Statistiques | Webhooks | Domaines, membres, clés |
|---|---|---|---|---|
| lecteur | Lecture seule | Lire, lancer des exports CSV | Lister les endpoints | Voir les domaines et les membres |
| éditeur | Créer, modifier, supprimer, créer en masse | Lire, lancer des exports CSV | Lister les endpoints | Voir les domaines et les membres |
| administrateur | Tout ce que peut faire l'éditeur | Plus exports de données, rapports planifiés | Créer, modifier, rejouer | Gérer les domaines, membres, clés |
| propriétaire | Tout | Tout | Tout | Tout |
Un tableau de bord de rapports qui importe les nombres de clics dans un outil de BI a besoin du rôle de lecteur. Une tâche Google Sheets qui crée des liens de campagne a besoin du rôle d'éditeur. Presque aucune automatisation quotidienne ne nécessite le rôle d'administrateur, et je considérerais une clé de propriétaire comme un signal d'alerte : le propriétaire est destiné aux personnes qui gèrent l'espace de travail, et je ne vois aucune tâche d'automatisation qui en ait besoin.
Deux limites méritent d'être connues. Seuls les administrateurs et les propriétaires peuvent créer, lister ou révoquer des clés, de sorte qu'une clé de lecteur ou d'éditeur ne peut pas s'en créer une autre plus puissante. De plus, aucune clé, quel que soit son rôle, n'accède à l'API d'administration de la plateforme. Cette surface refuse entièrement l'authentification par clé API avec une réponse 403 et le message "admin access requires an interactive session". Une clé sert à intégrer un espace de travail, et rien de plus.
Pourquoi la gestion des webhooks nécessite une clé d'administrateur
C'est le point qui surprend le plus. La lecture de la liste des endpoints webhook est autorisée pour tous les membres, y compris les clés de lecteur. En revanche, créer un endpoint, modifier sa destination ou rejouer une livraison nécessite l'autorisation workspace.edit, détenue uniquement par les administrateurs et les propriétaires.
Le raisonnement est celui du flux permanent évoqué plus haut. Un éditeur peut créer mille liens et vous le remarquerez. Un éditeur qui pourrait ajouter un webhook attrape-tout dirigé vers son propre serveur recevrait ensuite chaque événement de lien, en silence. Les modifications des webhooks restent donc entre les mains des mêmes personnes que celles qui peuvent modifier les paramètres de l'espace de travail.
En pratique, configurez les webhooks une fois, manuellement, en tant qu'administrateur dans le tableau de bord. Donnez ensuite à l'automatisation qui les consomme une clé d'éditeur ou de lecteur pour ses appels API. Si vous connectez les webhooks pour les événements de lien à Slack ou à un CRM, le système qui reçoit les données n'a pas besoin d'une clé Elido. Il lui faut le secret de signature pour vérifier les charges utiles.
Vous voulez vérifier avant de connecter quoi que ce soit ? Créez un espace de travail gratuit, générez une clé de lecteur et une clé d'éditeur, puis essayez le même appel d'écriture avec chacune. Le 403 renvoyé pour la clé de lecteur vous en apprendra plus que n'importe quel tableau.
Stockage des clés : secret additionnel, hachage et préfixe
Un jeton se présente sous la forme elido_ suivie de 52 caractères en base32, générés à partir de 32 octets aléatoires. Vous voyez l'ensemble du jeton une seule fois, dans la réponse à l'appel de création. Ensuite, il disparaît définitivement de notre côté.
Ce que nous conservons est un HMAC-SHA256 du jeton, calculé avec un secret additionnel côté serveur stocké dans la configuration de l'application et non dans la base de données. À chaque requête, le jeton Bearer entrant, selon le schéma défini dans RFC 6750, est haché de la même manière, puis recherché par hachage. Une copie volée de la base de données n'est qu'une liste de hachages qui ne peuvent pas être vérifiés sans le secret additionnel, et le service de production refuse de démarrer si aucun secret n'est défini.
Pour vos propres repères, nous conservons les huit premiers caractères qui suivent elido_ comme préfixe d'affichage. La page des clés API affiche ce préfixe à côté du nom de la clé, de son rôle, de sa date de création, de son expiration, de l'heure de sa dernière utilisation et de sa dernière adresse IP utilisée, ainsi que du nombre total de requêtes et de requêtes échouées. Lorsqu'une clé apparaît quelque part dans un journal, le préfixe permet d'identifier laquelle sans que personne ait besoin de voir le secret complet.
Limites de débit, expiration et rotation des clés API
Chaque clé dispose de son propre compartiment de jetons, séparé de la limite par espace de travail, afin qu'un workflow qui s'emballe ne consomme pas le budget de toutes les autres opérations. Un administrateur peut remplacer la limite d'une clé, de 1 à 10 000 requêtes par seconde, ainsi que sa rafale (burst), de 1 à 20 000, ou supprimer ce remplacement pour revenir à la valeur par défaut. Au-delà de la limite, la clé reçoit une réponse 429 avec Retry-After: 1 et X-RateLimit-Scope: api_key, de sorte que votre logique de nouvelle tentative peut distinguer une limite de clé d'une limite d'espace de travail. Le guide des limites de débit et de l'idempotence explique comment réduire correctement le rythme des nouvelles tentatives.
L'expiration est facultative et définie à la création sous la forme d'un horodatage RFC 3339. Une fois cette date dépassée, la clé n'est tout simplement plus acceptée. La révocation se fait avec un seul DELETE. Elle est également idempotente.
Il n'existe pas de bouton unique "rotation", et cela ne me manque pas. La rotation se fait en trois étapes :
- Créez une nouvelle clé avec le même rôle et une nouvelle date d'expiration.
- Remplacez-la dans le gestionnaire d'identifiants de l'outil et vérifiez qu'un appel aboutit.
- Révoquez l'ancienne clé, puis vérifiez dans la liste que son heure de dernière utilisation ne bouge plus.
Chaque étape est inscrite dans le journal d'audit de l'espace de travail : api_key.created avec le nom et le rôle, api_key.revoked et api_key.rate_limit_set pour les remplacements de limite. Une analyse en arrière-plan s'exécute également toutes les cinq minutes et signale toute clé ayant effectué plus de 1 000 requêtes dont plus de 30 % ont échoué. Le signalement apparaît dans le journal d'audit et sur la clé. Aucune révocation automatique : désactiver une clé est une décision humaine, car une série de 404 provient aussi souvent d'un workflow défectueux que d'un attaquant.
Transmettre des clés API avec le moindre privilège à n8n, Make et Zapier
Les plateformes d'automatisation sont l'endroit où les clés finissent par être oubliées. Elles restent dans un gestionnaire d'identifiants, sont copiées dans des fichiers JSON de workflows exportés et survivent à la personne qui les a configurées. Deux habitudes sont utiles :
- Une clé par outil et par famille de workflows, nommée d'après son usage ("n8n: feuilles de campagne"). Sa révocation ne casse alors qu'un seul élément, et le journal d'audit indique quel outil a fait quoi.
- Le rôle d'éditeur pour tout ce qui crée des liens, le rôle de lecteur pour tout ce qui ne fait que lire, et une date d'expiration dans les deux cas.
C'est tout pour la liste. La suite relève du discernement. L'aide-mémoire OWASP sur la gestion des secrets explique bien comment éviter que les jetons apparaissent dans les journaux et les exports, là où les clés d'automatisation sont le plus souvent divulguées.
Pour la configuration propre à chaque outil, le guide du raccourcisseur d'URL n8n place la clé dans un identifiant Header Auth, et la comparaison Make vs IFTTT vs n8n vs Zapier indique où chaque plateforme la conserve. Zapier se connecte avec le même jeton, comme l'explique le guide d'automatisation Zapier. Pour la CI ou tout ce qui doit survivre au départ d'une personne, un utilisateur machine convient mieux : un compte de service avec son propre rôle, séparé de la clé de tout utilisateur humain.
Et la raison pour laquelle une clé ne doit jamais ouvrir les endpoints d'administration tient précisément à cette transmission. Une fois qu'un jeton se trouve dans un outil tiers, toute personne ayant un accès de modification aux workflows de cet outil peut l'utiliser. Vous faites confiance à toutes les personnes de leur côté, pas seulement aux vôtres.
Les jetons par portée sont prévus, mais pas encore disponibles
Les rôles sont volontairement larges, et parfois trop larges. Une clé d'éditeur qui ne crée que des liens peut aussi les supprimer, car la suppression fait partie du rôle d'éditeur. La solution consiste à utiliser des jetons par portée, comme links:write ou analytics:read, attachés directement à une clé et ajoutés par-dessus les rôles.
C'est prévu dans notre feuille de route et ce n'est pas encore livré. Aujourd'hui, les autorisations d'une clé sont son espace de travail et son rôle, sans niveau plus fin. Si vous avez besoin d'un contrôle plus strict dès maintenant, les deux leviers sont un rôle moins élevé et une expiration courte, ainsi que des clés séparées par tâche afin de réduire la portée de chaque incident. Le démarrage rapide de l'API et la référence de l'API et du SDK présentent le modèle actuel des clés avec du code fonctionnel, et les équipes qui souhaitent aussi un contrôle au niveau de l'identité peuvent consulter les informations sur SCIM et SSO pour les outils marketing.
Lisez l'article de référence : la checklist de sécurité d'un raccourcisseur d'URL couvre les contrôles autour de la clé, de l'analyse des URL aux listes d'autorisation IP.
Articles connexes du blog
- API de raccourcissement d'URL : démarrage rapide de 30 minutes en cinq langues
- Raccourcisseur d'URL n8n : nœud HTTP Request ou nœud communautaire Elido
- Automatisation des liens courts : Make vs IFTTT vs n8n vs Zapier
- Webhooks pour les événements de lien
- Raccourcisseur d'URL GitHub Actions : des liens courts depuis votre CI
Questions fréquentes
Que sont les autorisations des clés API ?
Ce sont l'ensemble des actions qu'une clé est autorisée à effectuer sur une API : les ressources qu'elle peut lire, celles qu'elle peut modifier et le compte concerné. Dans Elido, les autorisations d'une clé proviennent de l'espace de travail dans lequel elle a été créée et du rôle choisi à sa création. La même clé ne peut donc pas agir dans un autre espace de travail ni dépasser ce rôle.
Que signifie le principe du moindre privilège pour les clés API ?
Cela signifie que chaque clé reçoit l'ensemble minimal d'autorisations nécessaires à sa fonction, et rien de plus. Un tableau de bord qui lit uniquement le nombre de clics reçoit une clé de lecteur, un workflow qui crée des liens reçoit une clé d'éditeur et les clés d'administrateur sont réservées aux rares tâches qui gèrent les webhooks, les domaines ou les membres. Une clé divulguée ne peut alors faire que ce que cette tâche pouvait faire.
Quelle est la différence entre les portées et les rôles des clés API ?
Une portée est une autorisation précise, comme links:write, attachée directement à un jeton, tandis qu'un rôle est un ensemble nommé d'autorisations, comme éditeur. Les rôles sont plus faciles à comprendre, les portées sont plus fines. Les clés Elido utilisent aujourd'hui des rôles d'espace de travail, et les jetons par portée sont prévus par-dessus, mais ne sont pas encore disponibles.
À quelle fréquence faut-il effectuer la rotation des clés API ?
Les recommandations courantes prévoient tous les 30 à 90 jours, ainsi qu'immédiatement lorsqu'une personne ayant vu la clé quitte l'équipe, lorsque la clé apparaît dans un journal ou lorsque son trafic semble anormal. Définir une date d'expiration à la création transforme ce calendrier en arrêt automatique plutôt qu'en rappel ignoré dans un agenda.
Une clé API peut-elle accéder aux endpoints d'administration ?
Sur Elido, non. L'API d'administration de la plateforme accepte uniquement une session interactive avec authentification et répond 403 à une clé API, quel que soit le rôle de la personne qui l'a créée. Les paramètres de l'espace de travail qui nécessitent des droits d'administration restent accessibles, mais uniquement avec une clé créée avec le rôle d'administrateur ou de propriétaire.
Comment les clés API doivent-elles être stockées chez le fournisseur ?
Jamais en clair. Le fournisseur doit stocker un hachage avec clé du jeton et ne vous montrer ensuite qu'un préfixe court, afin qu'une copie de la base de données seule ne permette pas d'appeler l'API. Elido hache chaque jeton avec HMAC-SHA256 et un secret additionnel côté serveur, puis affiche le jeton complet une seule fois.
Essayer Elido
Collez une URL, obtenez un lien court
Sans inscription. Lien actif 30 jours. Inscrivez-vous pour le garder pour toujours.
Gratuit, sans inscription · 2 par jour