Clés API

Choisissez des droits d’accès personnels ou de service, enregistrez le secret dès sa création et remplacez les identifiants sans perdre de vue les appelants qui les utilisent.

Une clé API permet à un appelant d’agir avec des droits d’accès définis. Les droits d’une clé personnelle dépendent de l’appartenance et des permissions de la personne qui l’a créée. Une clé de service appartient à l’organisation : l’automatisation peut ainsi continuer à fonctionner indépendamment du départ d’un ou d’une collègue. Avec RBAC, une clé de service peut aussi disposer de son propre rôle et de son propre périmètre de ressources.

Le secret s’affiche à la création et ne peut plus être récupéré ensuite dans la fiche de la clé. Enregistrez-le immédiatement dans un gestionnaire de secrets ou dans le stockage d’identifiants pris en charge par l’appelant. Ne l’incluez pas dans des fichiers source, des configurations committées, des captures d’écran ou des messages à l’assistance.

Utilisez une clé personnelle pour agir en votre nom #

Dans Paramètres → Clés API → Personnel de l’organisation sélectionnée, créez une clé personnelle et donnez-lui un nom. Chaque membre peut en créer une pour son propre usage. Les droits d’accès de cette clé dépendent de l’appartenance actuelle et des permissions effectives de la personne qui l’a créée. Contrairement à une clé de service, elle ne peut pas recevoir de rôle distinct ni de périmètre par moteur de localisation.

Cette clé convient à un appelant local qui agit au nom de la personne qui l’utilise. Si le membre quitte l’organisation ou perd ses droits, l’accès de la clé change aussi. Utilisez une clé de service lorsque l’automatisation de l’organisation ne doit pas dépendre du maintien de l’accès de cette personne.

Créez une clé de service #

Dans Paramètres → Clés API → Organisation de l’organisation sélectionnée, sélectionnez Nouvelle clé d’organisation. Les clés de service sont disponibles avec toutes les offres. Leur création nécessite org:manage_api_keys.

Sans RBAC, les droits d’une clé de service ne peuvent pas être restreints : elle peut lire et traduire avec tous les moteurs de localisation de l’organisation. Le formulaire de création affiche une note à la place des champs de rôle et de moteur.

Cet accès de base ne permet pas à la clé de modifier ou de supprimer des moteurs de localisation, d’effectuer la relecture des traductions ni d’administrer l’organisation.

Avec RBAC, vous pouvez attribuer à la clé un rôle, un périmètre de moteurs de localisation, ou les deux, puis les modifier par la suite. L’appelant doit pouvoir déléguer le rôle sélectionné et traduire avec chaque moteur de localisation compris dans le périmètre. La permission de lecture seule ne suffit pas pour accorder un périmètre de traduction.

Les rôles de service autorisés sont engine:read et engine:translate. Un rôle doit appartenir à l’organisation et ne peut pas comporter de permissions d’administration plus étendues. Une clé de service peut aussi n’avoir aucun rôle et s’appuyer sur des droits explicitement accordés sur les ressources.

Configurez séparément le périmètre des moteurs de localisation et celui des ressources de contenu, puis vérifiez la valeur de chaque champ enregistré. Une mise à jour des droits d’accès peut échouer alors qu’une autre réussit. Les permissions du rôle et les droits explicitement accordés se cumulent ; un périmètre restreint n’annule pas les accès plus larges conférés par le rôle. Avec RBAC, la simple création d’une clé ne lui accorde aucun droit de traduction exploitable si elle ne dispose ni d’un rôle approprié ni de droits sur les ressources.

Utilisez l’interface de gestion des clés pour créer les clés et modifier leur périmètre. Si vous automatisez ce cycle de vie, vérifiez que le client choisi propose l’opération de gestion requise, sans supposer que tous les clients la prennent en charge.

Avant de supprimer RBAC

Si RBAC est supprimé, les clés de service ordinaires retrouvent un accès en lecture et en traduction à l’ensemble de l’organisation. Les restrictions de rôle et de moteur enregistrées ne limitent plus cet accès. Révoquez ou renouvelez les clés avant de supprimer RBAC si ces restrictions sont nécessaires. Les identifiants dédiés à un usage précis, comme les clés SCIM, sont soumis à des exigences d’accès distinctes.

Renouvelez ou révoquez un identifiant #

Le renouvellement consiste à remplacer la clé manuellement :

  1. Créez une clé de remplacement du type prévu, avec les droits d’accès strictement nécessaires.
  2. Enregistrez son secret dans le mécanisme de gestion des secrets de l’appelant.
  3. Mettez à jour les appelants qui en dépendent et vérifiez le bon fonctionnement d’une opération prévue de faible ampleur via l’interface qu’ils prennent en charge.
  4. Révoquez l’ancienne clé après vérification. Si une exposition impose de limiter immédiatement les risques, révoquez-la d’abord et tenez compte de l’interruption.
  5. Examinez les fiches des clés actuelles et les échecs des appelants pour repérer les dépendances oubliées.

Un membre de l’organisation ayant accès à la fiche d’une clé peut révoquer une clé personnelle ou de service ordinaire. Cette permission de révocation est plus large que celle permettant de créer ou de modifier le périmètre d’une clé de service. La révocation d’une clé SCIM nécessite le rôle Propriétaire de l’organisation. Lorsque vous évoquez la suppression d’une clé, utilisez son identifiant, et non son secret.

La révocation n’efface pas les copies conservées ailleurs et ne révoque pas les sessions du navigateur. Ce cycle de vie ne prévoit aucun calendrier automatique de renouvellement ou d’expiration.

Configurez l’appelant utilisé #

Les requêtes REST utilisent l’en-tête X-API-Key de l’API sélectionnée. Un code 401 signale un problème d’authentification ; un code 403 signale un refus d’accès. Vérifiez l’identifiant d’authentification dans le premier cas, et les permissions ainsi que le périmètre de ressources de l’entité appelante dans le second. Ne placez pas d’identifiants dans des URL improvisées.

Consultez Authentification de l’API, Authentification de la CLI ou le contrat de connexion MCP pour connaître les modalités de transmission et de stockage de l’appelant. Le moteur de localisation sélectionné doit rester dans les limites des droits d’accès de cet appelant.