Les permissions d'une clé API décident de ce qu'une clé fuitée peut casser. Dans un outil de liens, le réglage sûr par défaut est une clé liée à un seul espace de travail, plafonnée au rôle le plus bas qui fait le travail, stockée sous forme de hash avec pepper, limitée en débit séparément et configurée pour expirer. Une clé qui ne fait que créer des liens n'a rien à faire avec les webhooks, les membres ou la facturation, et elle ne devrait jamais ouvrir un endpoint d'administration. C'est cela, le moindre privilège, et l'essentiel tient à des choix faits pendant les trente secondes que prend la création de la clé.
J'ai lu beaucoup de configurations d'automatisation l'an passé, et le schéma se répète : quelqu'un colle sa propre clé toute-puissante dans n8n un vendredi après-midi, ça marche, et plus personne n'y pense jusqu'au départ de cette personne ou jusqu'à ce que l'export du workflow atterrisse dans un drive partagé. Le reste de cet article explique comment fonctionnent les scopes et les rôles de clés API dans un produit de liens courts, ce que chaque rôle peut réellement faire, et comment confier une clé à un outil d'automatisation sans lui confier l'espace de travail.
Il accompagne notre checklist de sécurité des raccourcisseurs d'URL, plus large, qui couvre le scan, la signature des webhooks et les journaux d'audit sur toute la plateforme. Celui-ci zoome sur la clé elle-même.
Ce que signifient les permissions de clé API dans un outil de liens
L'API d'un outil de liens touche plus que des liens. Le même token qui crée go.example.com/spring-sale peut, selon ses permissions, lire les analytics de clics, ajouter un domaine personnalisé, inviter un membre, ou enregistrer un webhook qui envoie chaque événement vers un serveur extérieur. Ce dernier point m'inquiète. Un webhook est un flux de données permanent que celui qui le crée peut pointer vers n'importe quel serveur, et personne dans votre équipe ne le remarquerait forcément avant des semaines.
Les permissions ont donc trois axes. Où la clé fonctionne-t-elle (quel compte ou espace de travail) ? Que peut-elle y faire (lire, écrire, administrer) ? Et pendant combien de temps, et à quel débit ? La définition du glossaire du NIST pour le moindre privilège (consultée le 2026-10-24) dit que chaque entité reçoit les autorisations minimales dont elle a besoin pour remplir sa fonction, et les trois axes en font partie. Une clé en lecture seule qui n'expire jamais et n'a pas de rate limit reste sur-privilégiée dans le temps.
Clés API liées à l'espace de travail : une clé, un espace de travail
Sur Elido, chaque clé est émise dans un espace de travail et y reste. Appelez les endpoints d'un autre espace de travail avec elle et vous obtenez une 404, la même réponse que pour un espace de travail inexistant, donc une clé ne peut même pas confirmer que d'autres espaces de travail existent.
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 token fuité d'un projet client ouvrirait tous les clients. Les clés API liées à l'espace de travail réduisent le rayon d'impact à un espace de travail.
La clé est aussi plafonnée au rôle choisi à sa création, et ne dépasse jamais le rôle actuel de son créateur. L'accès effectif est le plus bas des deux. Rétrogradez en editor l'admin qui a créé une clé : la clé descend avec lui. Les permissions personnalisées attachées à ce membre sont aussi écartées dès que le rôle de la clé est le plus bas, car elles décrivent la personne, pas la clé.
Clés API par rôle : ce que peut faire chaque rôle
Les clés Elido utilisent les mêmes quatre rôles que les personnes : viewer, editor, admin et owner. Vous en choisissez un à la création de la clé ; omis, il vaut editor par défaut, ce qui couvre la tâche d'automatisation habituelle (créer des liens et lire les analytics) sans portée admin.
Voici ce que cela donne en pratique pour ce que les intégrations touchent d'ordinaire.
| Rôle | Liens et campagnes | Analytics | Webhooks | Domaines, membres, clés |
|---|---|---|---|---|
| viewer | Lecture seule | Lecture, lancement de jobs d'export CSV | Lister les endpoints | Voir domaines et membres |
| editor | Créer, modifier, supprimer, créer en masse | Lecture, lancement de jobs d'export CSV | Lister les endpoints | Voir domaines et membres |
| admin | Tout ce que fait editor | Plus config d'export de données S3, rapports e-mail planifiés | Créer, modifier, rejouer | Gérer domaines, membres, clés |
| owner | Tout | Tout | Tout | Tout |
Un dashboard de reporting qui tire les compteurs de clics vers un outil de BI a besoin de viewer. Un job Google Sheets qui génère des liens de campagne a besoin d'editor. Presque rien dans l'automatisation quotidienne ne demande admin, et je considérerais une clé owner comme un mauvais signe : owner existe pour les humains qui dirigent l'espace de travail, et je ne vois aucune tâche d'automatisation qui l'exige.
Deux limites à connaître. Seuls les admins et les owners détiennent la permission api_keys.manage, donc une clé viewer ou editor ne peut ni lister ni révoquer des clés. Et créer une clé, ou changer son rate limit, demande une personne connectée : une clé API de n'importe quel rôle reçoit un 403 (« this action requires an interactive session »). Une clé admin fuitée ne peut pas générer un remplaçant sans expiration. Elle peut quand même lister et révoquer des clés. Et aucune clé, quel que soit son rôle, n'atteint l'API d'administration de la plateforme. Cette surface refuse net l'authentification par clé API avec un 403 et le message « admin access requires an interactive session ». Une clé sert à une intégration d'espace de travail, et c'est tout ce qu'elle ouvre.
Pourquoi la gestion des webhooks exige une clé admin
C'est ce qui surprend le plus. Lire la liste des endpoints de webhook est permis à tout membre, clés viewer comprises. Mais créer un endpoint, changer sa cible ou rejouer une livraison exige la permission workspace.edit, que seuls admin et owner détiennent.
Le raisonnement est le problème du flux permanent évoqué plus haut. Un editor peut créer mille liens et vous le verrez. Un editor qui pourrait ajouter un webhook fourre-tout pointant vers son propre serveur recevrait désormais tous les événements de liens, en silence. Les modifications de webhooks relèvent donc des mêmes personnes qui peuvent changer les réglages de l'espace de travail.
En pratique, configurez les webhooks une fois, à la main, en tant qu'admin dans le dashboard. Donnez ensuite à l'automatisation qui les consomme une clé editor ou viewer pour ses appels API. Si vous branchez des webhooks d'événements de liens sur Slack ou un CRM, le côté récepteur n'a pas besoin de clé Elido du tout ; il a besoin du secret de signature pour vérifier les payloads.
Envie d'une preuve avant de brancher quoi que ce soit ? Créez un espace de travail gratuit, générez une clé viewer et une clé editor, et essayez le même appel d'écriture avec chacune. Le 403 sur la clé viewer en dit plus que n'importe quel tableau.
Comment les clés sont stockées : pepper, hash et préfixe
Un token ressemble à elido_ suivi de 52 caractères en base32, générés à partir de 32 octets aléatoires. Vous le voyez en entier une seule fois, dans la réponse à l'appel de création. Ensuite, il a définitivement disparu de notre côté.
Ce que nous gardons est un HMAC-SHA256 du token, calculé avec un pepper côté serveur qui vit dans la configuration de l'application, pas dans la base. À chaque requête, le Bearer token entrant (le schéma défini dans la RFC 6750, consultée le 2026-10-24) est haché de la même façon et recherché par hash. Un dump de base volé n'est donc qu'une liste de hash que personne ne peut vérifier sans le pepper. Pas de pepper, pas de démarrage : le service de production refuse de démarrer sans qu'il soit défini.
Pour vos propres registres, nous stockons les huit premiers caractères après elido_ comme préfixe d'affichage, et la page des clés API montre ce préfixe à côté du nom de la clé, de son rôle, de sa date de création, de son expiration, de sa dernière utilisation et de la dernière IP, plus les totaux de requêtes et de requêtes échouées. Quand une clé apparaît dans un log quelque part, le préfixe vous dit laquelle c'est. Personne n'a besoin de voir le secret complet.
Rate limits, expiration et rotation des clés API
Chaque clé a son propre token bucket, distinct de la limite par espace de travail, donc un workflow qui s'emballe ne peut pas consommer le budget de tout le reste. Un admin connecté peut surcharger le débit d'une seule clé de 1 à 10 000 requêtes par seconde et son burst de 1 à 20 000, ou effacer la surcharge pour revenir au défaut. Au-delà de la limite, la clé reçoit un 429 avec Retry-After: 1 et X-RateLimit-Scope: api_key, de sorte que votre logique de retry distingue un plafond de clé d'un plafond d'espace de travail. Le guide des rate limits et de l'idempotence explique comment espacer correctement les tentatives.
L'expiration est facultative et se fixe à la création sous forme de timestamp RFC 3339. Une fois passée, la clé cesse simplement de correspondre. La révocation est un simple DELETE. Elle est aussi idempotente.
Il n'y a pas de bouton « rotation » unique, et il 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 expiration.
- Mettez-la dans le magasin d'identifiants de l'outil et vérifiez qu'un appel réussit.
- Révoquez l'ancienne clé, puis vérifiez dans la liste que sa date de dernière utilisation ne bouge plus.
Chaque étape arrive 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 surcharges. Un scan en arrière-plan tourne aussi toutes les cinq minutes et signale toute clé ayant plus de 1 000 requêtes dont plus de 30 % ont échoué. Le signalement va dans le journal d'audit et sur la clé. Pas de révocation automatique. Tuer une clé est une décision humaine, car une rafale de 404 est aussi souvent un workflow cassé qu'un attaquant.
Remettre des clés API à moindre privilège à n8n, Make et Zapier
Les plateformes d'automatisation sont l'endroit où les clés vont se faire oublier. Elles dorment dans un magasin d'identifiants, se retrouvent copiées dans le JSON exporté des workflows et survivent à la personne qui les a configurées. Deux habitudes aident :
- Une clé par outil et par famille de workflows, nommée d'après lui (« n8n: campaign sheets »). La révoquer ne casse alors qu'une seule chose, et le journal d'audit dit quel outil a fait quoi.
- Editor pour tout ce qui crée des liens, viewer pour tout ce qui ne fait que lire, et une date d'expiration sur les deux.
La liste s'arrête là ; le reste est affaire de jugement. Le Secrets Management Cheat Sheet d'OWASP (consulté le 2026-10-24) est une bonne lecture sur la façon de garder les tokens hors des logs et des exports, là où les clés d'automatisation fuient d'ordinaire.
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, IFTTT, n8n et Zapier indique où chaque plateforme la range. Zapier se connecte avec le même token, d'après le pas-à-pas 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 token, distinct de la clé de tout humain. Comme les clés, les utilisateurs machine sont créés par un admin connecté, jamais par un token.
Et la raison pour laquelle une clé ne doit jamais ouvrir d'endpoints d'administration est précisément cette remise. Dès qu'un token vit dans un outil tiers, toute personne ayant un accès en édition aux workflows de cet outil peut s'en servir. Vous faites confiance à tout le monde de leur côté, pas seulement du vôtre.
Les tokens par scope sont prévus, pas actifs
Les rôles sont volontairement grossiers, et parfois trop. Une clé editor qui ne fait que créer des liens peut aussi les supprimer, car supprimer fait partie du rôle editor. Le remède, ce sont les tokens par scope, comme links:write ou analytics:read, attachés directement à une clé, par-dessus les rôles.
C'est sur notre roadmap et pas livré. Aujourd'hui, les permissions d'une clé sont son espace de travail plus son rôle, rien de plus fin. Si vous avez besoin d'un contrôle plus serré dès maintenant, les deux leviers sont un rôle plus bas et une expiration courte, plus des clés séparées par tâche pour que le rayon d'impact de chacune reste petit. Le quickstart de l'API et la référence API et SDK montrent le modèle de clés actuel en code fonctionnel, et les équipes qui veulent aussi un contrôle au niveau de l'identité peuvent lire SCIM et SSO pour les outils marketing.
Lire le cornerstone : la checklist de sécurité des raccourcisseurs d'URL couvre les contrôles autour de la clé, du scan d'URL aux allowlists IP.
Sur le même sujet
- API de raccourcisseur d'URL : un quickstart de 30 minutes en cinq langages
- Raccourcisseur d'URL n8n : nœud HTTP Request ou nœud communautaire Elido
- Automatisation des liens courts : Make, IFTTT, n8n et Zapier
- Webhooks pour les événements de liens
- Raccourcisseur d'URL GitHub Actions : des liens courts depuis votre CI
Questions fréquentes
Que sont les permissions d'une clé API ?
C'est l'ensemble des actions qu'une clé est autorisée à effectuer sur une API : quelles ressources elle peut lire, lesquelles elle peut modifier, et dans quel compte. Dans Elido, les permissions d'une clé viennent de l'espace de travail où elle a été émise et du rôle choisi à sa création, donc la même clé ne peut pas agir dans un autre espace de travail ni au-dessus de ce rôle.
Qu'est-ce que le moindre privilège pour les clés API ?
Cela signifie que chaque clé reçoit le plus petit ensemble de permissions dont sa tâche a besoin, et rien de plus. Un dashboard qui ne lit que les compteurs de clics reçoit une clé viewer, un workflow qui crée des liens reçoit une clé editor, et les clés admin sont réservées aux rares tâches qui gèrent webhooks, domaines ou membres. Une clé fuitée ne peut alors faire que ce que faisait cette tâche.
Quelle différence entre scopes et rôles pour les clés API ?
Un scope est une permission étroite comme links:write attachée directement à un token, tandis qu'un rôle est un lot nommé de permissions comme editor. Les rôles sont plus faciles à raisonner ; les scopes sont plus fins. Les clés Elido utilisent aujourd'hui les rôles d'espace de travail, et des tokens par scope sont prévus par-dessus mais pas encore actifs.
À quelle fréquence faut-il faire tourner les clés API ?
La règle courante est tous les 30 à 90 jours, plus immédiatement quand une personne ayant vu la clé part, quand la clé apparaît dans un log ou quand son trafic paraît anormal. Fixer une date d'expiration à la création transforme ce calendrier en arrêt net au lieu d'un rappel que personne ne suit.
Une clé API peut-elle accéder aux endpoints d'administration ?
Sur Elido, non. L'API d'administration de la plateforme n'accepte qu'une session interactive connectée et répond 403 à une clé API, quel que soit le rôle de la personne qui l'a créée. Les réglages d'espace de travail qui exigent des droits admin restent accessibles, mais seulement par une clé créée avec le rôle admin ou owner.
Comment le fournisseur doit-il stocker les clés API ?
Jamais en clair. Le fournisseur doit stocker un hash à clé du token et ne vous montrer ensuite qu'un court préfixe, de sorte qu'une copie de la base seule ne permette pas d'appeler l'API. Elido hache chaque token avec HMAC-SHA256 et un pepper côté serveur, et affiche le token 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.
Sans inscription. Créez un compte gratuit pour 50 liens par mois.