Rôles et permissions des clés API

Chaque clé API Elido est associée à un rôle. Le rôle détermine ce que la clé peut faire. Choisir le rôle le moins puissant pour chaque cas d'utilisation limite l'impact en cas de fuite de la clé.

Les trois rôles#

Rôle	Ce qu'il peut faire
viewer	Lire les liens, les analyses et les paramètres de l'espace de travail. Ne peut rien créer, mettre à jour ou supprimer.
editor	Tout ce que le viewer peut faire, plus créer/mettre à jour/supprimer des liens, gérer les webhooks et exécuter des imports en masse.
admin	Tout ce que l'editor peut faire, plus gérer les membres de l'espace de travail, la facturation, les clés API et les règles IP.

Vous définissez le rôle lorsque vous créez une clé dans Settings → API keys. Vous ne pouvez pas modifier le rôle d'une clé après sa création — émettez une nouvelle clé avec le bon rôle et révoquez l'ancienne.

Quel rôle utiliser#

Tableaux de bord analytiques et intégrations en lecture seule — utilisez viewer. Un outil BI tiers, une page de statut extrayant le nombre de clics ou un script de rapport interne n'ont besoin que de lire les données.

Pipelines CI/CD qui raccourcissent des liens — utilisez editor. Votre script de déploiement créant des liens de campagne, votre intégration CMS générant des URLs courtes et la plupart des automatisations Zapier/Make entrent dans cette catégorie.

Automatisation administrative — utilisez admin uniquement lorsque l'intégration a réellement besoin de gérer les membres ou la facturation. C'est inhabituel. La plupart des intégrations qui "semblent admin" ne sont en réalité que des editors.

Serveur MCP / agent AI — editor est le bon choix par défaut, à moins que l'agent n'ait besoin d'inviter des membres. Le paquet @elido/mcp-server respecte le rôle de la clé.

Correspondance rôle-point de terminaison#

Une référence rapide pour les appels API courants :

GET    /v1/links              → viewer
POST   /v1/links              → editor
PUT    /v1/links/:id          → editor
DELETE /v1/links/:id          → editor
GET    /v1/analytics/clicks   → viewer
GET    /v1/workspace          → viewer
POST   /v1/workspace/members  → admin
POST   /v1/api-keys           → admin

La référence complète se trouve sur /api.

Erreurs d'inadéquation de portée#

Lorsqu'une clé n'a pas la permission pour un point de terminaison, l'API renvoie :

{
  "error": "forbidden",
  "message": "this key requires the admin role to manage workspace members",
  "required_role": "admin",
  "key_role": "editor"
}

Le champ required_role vous indique exactement ce dont vous avez besoin. La solution consiste à émettre une nouvelle clé avec le rôle supérieur (si c'est intentionnel) ou à reconsidérer si l'intégration doit réellement effectuer cette opération.

Erreurs courantes :

• Utiliser une clé viewer pour créer des liens. Solution : émettez une clé editor.
• Utiliser une clé editor pour inviter un membre de l'équipe à partir d'un script. Solution : émettez une clé admin, ou utilisez le tableau de bord à la place.
• Confondre le rôle d'adhésion au niveau de l'espace de travail (Owner/Member) avec le rôle de la clé API. Ce sont des concepts distincts. Un membre de l'équipe ayant un accès "Member" peut toujours créer une clé API de rôle admin pour ses propres intégrations — ses permissions sur le tableau de bord ne sont pas héritées par la clé.

Dépannage#

403 sur un point de terminaison qui devrait être autorisé. Vérifiez à nouveau le rôle de la clé dans Settings → API keys — il est indiqué dans la colonne Rôle. Si le rôle semble correct, confirmez que vous envoyez l'en-tête Authorization: Bearer <token>, et non un en-tête d'authentification Basic ou un paramètre de requête.

401 Unauthorized. La clé est soit révoquée, soit le jeton est erroné. Vérifiez la colonne Statut pour un badge revoked. Si la clé est active, vérifiez que vous avez copié le jeton complet au moment de la création.

La clé fonctionne pour les lectures mais échoue pour les écritures. Votre clé est probablement une clé viewer. Émettez une nouvelle clé editor.

J'ai besoin de permissions différentes par intégration. Émettez une clé par intégration. La création de clés est gratuite et il est facile de les révoquer individuellement, il n'y a donc aucune raison de partager une clé entre deux systèmes.