Clés API

Créez, examinez et révoquez les clés API de votre organisation pour la Direct API et l’API Partenaire.

Une clé API permet à un autre système d’utiliser Morphic sans que personne l’ouvre : lancer vos workflows via l’API Partenaire, ou générer et modifier des médias via la Direct API. L’onglet « Clés d’API » est visible uniquement par les administrateurs.

Accédez directement ici : studio.morphic.com/settings/api-keys

La page des clés API, avec l'URL de base, l'identifiant de l'organisation et le bouton pour créer une clé

Une clé appartient à l’organisation

et non à la personne qui l’a créée. Elle continue de fonctionner lorsqu’elle la quitte, chaque administrateur la voit répertoriée et peut la révoquer, et chaque exécution qu’elle lance est facturée à l’organisation.

Créez une clé

Ouvrez l’onglet

Ouvrez le menu déroulant de l’organisation (le logo Morphic, en haut à gauche), sélectionnez Paramètres, puis cliquez sur « Clés d’API » dans la barre latérale gauche.

La barre latérale des paramètres, avec Clés API sélectionné en dernier parmi les écrans de l’organisation

Cliquez sur Nouvelle clé

Donnez-lui un nom que vous reconnaîtrez dans un mois : le système dans lequel elle sert, pas « clé 2 ».

Le formulaire d'une nouvelle clé API : nom, portées, workflows, limites de crédits et expiration

Choisissez ses portées

Ne choisissez que ce dont la clé a besoin. Les trois premières servent à l’API Partenaire, les autres à la Direct API ; celles-ci apparaissent une fois que Morphic a activé la Direct API pour votre organisation.

  • workflows:read : lire un workflow et les entrées qu’il prend
  • runs:write : lancer des exécutions et enregistrer des points de terminaison de webhook
  • runs:read : lire le statut d’une exécution et ses artefacts terminés, et lister les points de terminaison de webhook
  • projects:read : lire les projets et leurs fichiers
  • assets:read : rechercher et lire des assets
  • assets:write : téléverser des assets et les modifier
  • generations:write : générer des images, de la vidéo et de l’audio, ce qui dépense des crédits

Cochez ensuite la case pour accepter les Conditions d’utilisation de Morphic, y compris leur section consacrée à l’API pour les développeurs.

Limitez-la à des workflows spécifiques

Facultatif, et utile. Cochez « Limiter cette clé à certains workflows » et choisissez-les. L’exécution de tout autre élément est refusée, ce qui limite les dégâts si la clé est divulguée. Si elle n’est pas cochée, la clé peut lancer tous les workflows que l’organisation peut lancer.

« Limitez cette clé à des workflows spécifiques » coché dans le formulaire de nouvelle clé, avec un champ de recherche et les workflows de l’organisation à choisir

Définissez ses limites de crédit

Définissez « Crédits que cette clé pourra dépenser au total », ou choisissez « Aucune limite totale (illimité) ». Les plafonds quotidiens et mensuels sont facultatifs ; laissez l’un vide pour laisser cette période sans plafond.

Un total vaut la peine d’être défini. Choisissez-le en fonction de ce que l’intégration devrait pouvoir dépenser avant qu’on ne le réexamine, et non de ce qu’elle dépensera : c’est un disjoncteur, pas un budget. Un plafond de période ne peut pas être supérieur au total, car le total s’appliquerait en premier.

Les crédits pour une exécution lancée avec la clé sont facturés à l’organisation et imputés aux limites de cette clé. Une exécution lancée par la clé continue d’être imputée à celle-ci même si quelqu’un rejoint ensuite la conversation et prend le relais. Sinon, un collègue répondant à une question déplacerait le reste de l’exécution vers le pool général de l’organisation. La propre limite de crédit de cette personne, si elle en a une, s’applique aussi.

Un jour est un jour UTC et un mois un mois civil UTC. Une facturation qui ferait dépasser à la clé l’une de ses limites est refusée, et le message nomme la clé et la limite atteinte.

Choisissez une expiration

Jamais, 30 jours, 90 jours ou un an. Une clé expirée cesse de s’authentifier d’elle-même, ce qui est la forme de rotation la moins coûteuse.

Copier le secret

Le secret n’est affiché qu’une seule fois. Morphic n’en conserve qu’un hachage, il ne peut donc pas être réaffiché. Copiez-le dans votre gestionnaire de secrets avant de fermer la boîte de dialogue.

Quiconque détient la clé peut lancer des exécutions qui dépensent les crédits de votre organisation. Ne l’intégrez jamais dans le code, ne la mettez jamais dans un navigateur, ne l’envoyez jamais par e-mail ou par chat. Si elle fuit, révoquez-la.

Ce que montre la liste

Chaque clé affiche son nom, s’il s’agit d’une clé de production ou de test, les premiers caractères de son secret (suffisants pour le faire correspondre à vos propres enregistrements), ses portées, combien de workflows elle peut exécuter, ses limites de crédit et la date de sa dernière utilisation. Les clés expirées et révoquées restent listées afin que vous puissiez voir ce qui leur est arrivé.

Une organisation peut en détenir jusqu’à 10 clés pouvant s’authentifier à la fois. Les clés expirées et révoquées ne comptent pas dans ce total.

Modifier les limites de crédit d’une clé

  1. Trouvez la clé dans la liste.
  2. Cliquez sur le menu « … » à côté et sélectionnez « Modifier les limites ».
  3. Modifiez le total, ou un plafond quotidien ou mensuel, puis enregistrez. Supprimez un plafond pour le lever.

Les nouvelles limites s’appliquent à partir de la prochaine facturation de la clé, y compris pour les exécutions qu’elle a déjà lancées. C’est donc la solution lorsqu’une exécution s’arrête à la limite de la clé, et cela fonctionne aussi sur une clé révoquée : ses exécutions continuent d’être imputées à celle-ci, donc diminuer ses limites est la manière de les arrêter.

Révoquer une clé

  1. Trouvez la clé dans la liste.
  2. Cliquez sur le menu « … » à côté et sélectionnez « Révoquer la clé ».
  3. Confirmez.

Les appels qui l’utilisent commencent à échouer en quelques secondes. Les exécutions déjà en cours se terminent et restent facturées. Révoquer une clé ne peut pas être annulé. Pour renouveler une clé, créez d’abord le remplacement, transférez votre trafic vers lui, puis révoquez l’ancienne.

Où la dépense apparaît

Les crédits dépensés via l’API sont facturés à l’organisation et attribués à la clé qui les a dépensés. Dans Utilisation des crédits, la dépense de l’API apparaît comme un membre de plus, « API », et un débit d’une clé nommée comme « API · » suivi du nom de la clé.

  • Dans « Aperçu », activez « Répartir l’API par clé » pour ventiler la dépense de l’API clé par clé.
  • Une exécution de l’API Partenaire lancée avec un user_email qui n’est pas celui d’un de vos membres apparaît sous cet e-mail dans « Historique d’utilisation », ce qui vous permet de voir ce que chacun de vos propres utilisateurs a dépensé. Une exécution dont le user_email appartient à un membre est comptée pour ce membre. Voir Lancer une exécution de workflow.

Si vous rencontrez le moindre problème ou si vous avez des questions, n’hésitez pas à nous contacter. Nous serons ravis de vous aider. Écrivez-nous à support@morphic.com.

Sur cette page