Les clés d’API permettent à votre code et à votre CI de poser des questions et de lire les résultats. Pour les assistants IA comme Claude ou ChatGPT, connectez-vous avec OAuth : aucune clé n’est nécessaire.

Créer une clé

  1. Allez dans Développeurs dans le portail et choisissez Créer une clé.
  2. Donnez-lui le nom de l’endroit où elle servira, par exemple « CI » ou « bot tarifs ».
  3. Choisissez ses permissions et un plafond de dépense quotidien.
  4. Confirmez votre identité. La clé commence par fh_live_ et ne s’affiche qu’une fois : copiez-la tout de suite dans votre coffre à secrets.

Nous ne conservons qu’une empreinte (hash) de la clé ; nous ne pouvons donc pas vous la remontrer. Si vous la perdez, renouvelez-la.

Permissions

  • questions:read : résultats et listes.
  • questions:write : estimer, demander, annuler, partager, envoyer des fichiers.
  • templates:read : modèles à prix fixe.
  • account:read : solde et historique.
  • webhooks:read : voir les endpoints de webhook et leurs envois.
  • webhooks:write : ajouter, modifier, renouveler le secret, tester, rejouer et supprimer des endpoints de webhook.
  • apps:read : voir les espaces de travail Slack où 50heads est ajouté, avec le plafond quotidien de chacun.
  • apps:write : modifier le plafond quotidien d’un espace de travail Slack, ou le retirer. Voir Utiliser 50heads dans Slack.
  • events:read : lire le flux d’événements, pour l’export vers l’entrepôt de données et des outils comme Airbyte (ouverture progressive).

Pour les admins d’une organisation, là où elle a des comptes de service (en cours de déploiement) :

  • organization:read : voir l’organisation, ses domaines, ses règles de connexion, l’authentification unique, SCIM et les comptes de service.
  • organization:write : modifier les domaines, les règles de connexion et les réglages SCIM.
  • members:read : voir où un membre de l’organisation est connecté.
  • members:write : déconnecter un membre partout.
  • audit:read : lire et exporter le journal d’audit.

Créez la clé pendant que l’équipe de l’organisation est active. Les permissions d’organisation ne fonctionnent que tant que vous êtes admin de l’organisation : si vous ne l’êtes plus, la clé les perd aussitôt. Certains actes demandent toujours que vous soyez connecté, quelles que soient les permissions de la clé : la connexion d’authentification unique et la rendre obligatoire, les propriétaires de secours, les jetons SCIM, la durée de conservation des événements d’audit, les conservations légales, le transfert d’une équipe et les comptes de service. Pour un agent qui doit continuer à fonctionner quand quelqu’un part, utilisez un compte de service plutôt qu’une clé.

Ne donnez à chaque clé que ce dont elle a besoin. Les permissions de webhook, d’apps et d’organisation ne sont jamais cochées d’office. Voir Webhooks.

Modifier une clé

Choisissez Portées et plafonds sur une clé dans Développeurs pour la renommer et changer ses permissions, son plafond quotidien, son plafond par question ou les adresses depuis lesquelles elle peut servir. Retirer une permission, renommer et changer un plafond prennent effet aussitôt. Ajouter une permission demande d’abord de confirmer que c’est bien vous, comme pour créer une clé. Si vous utilisez la connexion en deux étapes, confirmez avec votre appli d’authentification, une clé d’accès ou un code de récupération.

Clés d’une équipe

Une clé créée pendant qu’une équipe est active dépense les crédits de l’équipe. Le propriétaire et les admins de l’équipe peuvent la voir, changer ses plafonds et la révoquer. Voir Votre équipe.

Renouveler et révoquer

Renouveler crée un nouveau secret pour la même clé avec les mêmes réglages. L’ancien secret fonctionne encore 24 heures, le temps de mettre à jour vos scripts, puis il s’arrête. Révoquer désactive la clé définitivement, en moins d’une seconde.

Anciennes clés

Les clés créées avant l’arrivée des permissions peuvent seulement poser des questions, lire les résultats, utiliser des modèles et voir votre solde, et n’ont aucun plafond quotidien. On ne peut plus en créer. Celles qu’il vous reste figurent dans Développeurs sous Anciennes clés, où vous pouvez les révoquer. Nous les retirerons après un préavis de 90 jours par e-mail. Créez une nouvelle clé avec des permissions et un plafond, passez votre code dessus, puis révoquez l’ancienne.

Gardez vos clés secrètes

Les clés sont faites pour les serveurs. Les requêtes avec une clé envoyées depuis un navigateur sont refusées, pour qu’une clé ne puisse pas être récupérée sur une page web. Ne commitez jamais de clé dans un dépôt.

Voir la documentation développeurs (en anglais) pour l’authentification, les erreurs et les limites de débit.