Authentification de l’API

Authentifiez les requêtes API et accordez les accès nécessaires à chaque opération.

Transmettez une clé API Lingo.dev dans l’en-tête X-API-Key. Utilisez https://api.lingo.dev/v2 comme URL de base pour les références de l’API présentées dans cette section.

http
GET /v2/organizations/YOUR_ORGANIZATION_ID/localization/jobs HTTP/1.1
Host: api.lingo.dev
X-API-Key: YOUR_API_KEY

Créez une clé depuis Clés API. Stockez-la dans l’environnement de votre serveur ou dans un gestionnaire de secrets. Ne l’incluez jamais dans des dépôts, des bundles destinés au navigateur, des URL ou des documents sources.

Choisir un identifiant d’authentification #

Une clé personnelle utilise les appartenances et les autorisations actuelles de son utilisateur. Une clé de service d’organisation appartient à l’organisation et convient à un service fonctionnant sans intervention humaine. Les autorisations accordées par son rôle et sur les ressources déterminent ses accès ; une autorisation explicite plus restreinte ne réduit pas les accès déjà accordés par son rôle.

L’API accepte également le jeton d’accès de session d’un utilisateur connecté sous la forme Authorization: Bearer <access-token>. Une personne chargée de la relecture peut utiliser sa session utilisateur ou sa clé personnelle pour soumettre des décisions de relecture. Les clés de service ne peuvent pas servir à prendre des décisions de relecture humaine, car ces actions doivent identifier une personne.

Utilisez une seule méthode d’authentification par requête. Les noms d’en-têtes sont insensibles à la casse.

Sélectionner l’organisation et le moteur #

Les routes propres à une organisation incluent orgId dans leur chemin. Pour trouver les identifiants d’organisation associés à un utilisateur ou à une clé personnelle, consultez GET /v2/users/me/memberships. Pour une clé de service, utilisez l’organisation à laquelle elle appartient. Les identifiants de moteur désignent le moteur configuré dans Studio ; utilisez GET /v2/organizations/:orgId/engines pour lister les moteurs accessibles.

Créer, démarrer, consulter et télécharger une tâche de localisation nécessite un accès à son organisation et un accès de traduction à son moteur. Le provisionnement nécessite l’autorisation de modifier ou de créer le moteur, ainsi que de créer les consignes demandées. La relecture des traductions s’appuie sur les autorisations et le routage de la personne chargée de la relecture.

Transmettre un identifiant d’organisation ou de moteur n’accorde aucun accès. Une ressource hors du périmètre de l’appelant peut renvoyer une erreur 404. Vérifiez donc à la fois l’identifiant et les autorisations de l’appelant lorsqu’une ressource connue reste introuvable.

Diagnostiquer un échec d’accès #

Consultez la réponse décrivant le problème ainsi que son statut HTTP. Une erreur 401 indique un identifiant d’authentification manquant, invalide ou expiré. Une erreur 402 signale une condition liée à la facturation ou au forfait, notamment une clé de service désactivée après une rétrogradation du RBAC. Une erreur 403 signale une autorisation refusée ou la nécessité d’une identité utilisateur. La configuration du moteur et les limites du compte nécessitent chacune des corrections spécifiques.

Conservez le champ type du problème, le statut et les identifiants de ressources non secrets pour faciliter le diagnostic. Ne consignez jamais l’en-tête d’authentification dans les journaux.

Renouveler une clé #

Créez la clé de remplacement, accordez-lui les accès nécessaires et mettez à jour le secret du service. Vérifiez qu’elle permet de récupérer une tâche existante et de télécharger un résultat avant de révoquer l’ancienne clé. Conservez les identifiants de tâches enregistrés : le renouvellement des identifiants d’authentification ne modifie pas l’identité des tâches.