Les clés API authentifient les requêtes vers l’API de localisation et le serveur MCP. Lingo.dev propose deux types de clés — choisissez celui qui correspond à la personne ou au système qui appelle l’API.
Deux types de clés#
| Personnelle | Service | |
|---|---|---|
| Propriétaire | L’utilisateur qui l’a créée | Aucun — conçue pour l’automatisation |
| Autorisation | Hérite du rôle RBAC du créateur et des autorisations par moteur | Dispose de son propre rôle et/ou de sa propre portée par moteur |
| Si le propriétaire perd l’accès | La clé perd l’accès elle aussi | Aucun impact ; l’accès dépend du rôle / de la portée propres à la clé |
| Forfait | Tous les forfaits | Enterprise (nécessite le droit RBAC) |
| Usage typique | Développement local, MCP, scripts ad hoc | Pipelines CI/CD, intégrations en production |
Les clés personnelles sont le choix par défaut. Les clés de service sont des artefacts au niveau de l’organisation, découplés de toute personne en particulier — c’est exactement ce qu’il faut pour des identifiants qui doivent survivre au départ d’employés et aux changements de rôle.
Créer une clé#
Ouvrez la page Clés API dans le tableau de bord. Les onglets Personal et Service sont séparés — l’onglet Service n’apparaît que si votre organisation dispose du forfait Enterprise.
Cliquez sur Create API key, donnez-lui un nom (par exemple, "MCP local", "clé de préproduction de Max"), puis copiez la clé depuis la boîte de dialogue de confirmation. La clé hérite de votre rôle RBAC actuel et de vos autorisations par moteur.
Visibilité de la clé
La clé API complète n’est affichée qu’une seule fois, au moment de sa création. Copiez-la et stockez-la en lieu sûr — vous ne pourrez plus la récupérer après avoir fermé la boîte de dialogue.
Clés de service et RBAC#
Les clés de service reprennent le même modèle que les utilisateurs : un utilisateur peut avoir un rôle au niveau de l’organisation (autorisations globales via Roles & Permissions) ET/OU des autorisations par moteur en étant ajouté à des moteurs spécifiques. Une clé de service fonctionne exactement de la même manière :
- Rôle uniquement — les autorisations du rôle s’appliquent à toute l’organisation. S’il inclut
engine:access, la clé peut accéder à tous les moteurs de l’organisation. - Aucun rôle + portée par moteur — la clé est limitée aux moteurs que vous cochez lors de sa création. Vous pourrez mettre la liste à jour plus tard depuis le bouton Engines x/y à côté de la clé.
- Rôle + portée par moteur — les deux niveaux d’autorité s’additionnent. Les autorisations globales du rôle priment s’il accorde
engine:access; sinon, la liste par moteur entre en jeu. - Ni l’un ni l’autre — la clé s’authentifie, mais ne peut accéder à aucun moteur. Utile comme solution temporaire pendant que vous configurez la portée, mais sans intérêt en production.
Des garde-fous anti-escalade s’appliquent à la création comme à la modification :
- Le rôle choisi doit appartenir à la même organisation.
- L’ensemble des autorisations du rôle doit être un sous-ensemble de
engine:access— les rôles plus étendus (par exemple, un rôle qui inclutorg:manage_team) sont rejetés. - Vous ne pouvez ajouter un moteur à la portée de la clé que si vous avez déjà vous-même accès à ce moteur.
Si votre forfait Enterprise expire
Les clés de service font partie du droit RBAC. Si ce droit est supprimé, toutes les clés de service de l’organisation sont désactivées — les requêtes renvoient un 403 avec un message qui pointe vers le forfait, et non vers la portée du moteur. Les clés personnelles ne sont pas concernées. Rétablissez le forfait Enterprise ou remplacez-les par une clé API personnelle.
Utiliser une clé#
Transmettez la clé API dans l’en-tête X-API-Key à chaque requête — le format est le même pour les deux types :
curl -X POST https://api.lingo.dev/process/localize \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"engineId": "eng_abc123", "sourceLocale": "en", "targetLocale": "de", "data": {"greeting": "Hello"}}'La même clé fonctionne aussi bien avec l’API de localisation qu’avec le serveur MCP.
Sécurité#
- Les clés sont stockées sous forme de hachages — Lingo.dev ne peut pas récupérer une clé après sa création. Pour la faire tourner, supprimez-la puis recréez-la.
- Les clés personnelles suivent en temps réel les autorisations de leur créateur. Si le rôle du créateur est rétrogradé ou si une autorisation sur un moteur est révoquée, la clé perd le même accès dès l’appel suivant.
- Une clé personnelle dont le créateur a été retiré de l’organisation continue de fonctionner uniquement tant que RBAC est désactivé (comportement historique). Dès que RBAC est activé, elle est refusée — remplacez-la avant qu’elle ne devienne orpheline.
- Les clés de service portent leur propre autorité. Toute modification du rôle ou de la portée depuis l’onglet Service prend effet immédiatement ; supprimer la clé révoque son accès.
- Il n’y a aucune limite au nombre de clés par organisation.
