Clés API
Créez des clés API pour connecter vos scripts et vos outils à Workbots.
Une clé API est un mot de passe destiné aux machines. Quand un de vos scripts ou un de vos outils veut lire ou écrire des données dans Workbots, il présente cette clé. Workbots reconnaît alors votre organisme et vérifie ce que la clé a le droit de faire.
Les clés API sont en cours de déploiement. L'interface est visible sous Paramètres → Développeur → Clés API. Cette page décrit ce que vous y voyez.
Le principe en trois idées
Une clé par usage
Un outil, une clé. Vous savez toujours qui fait quoi, et vous coupez un accès sans toucher aux autres.
Le minimum de droits
Une clé ne reçoit que les autorisations dont elle a réellement besoin.
Une durée limitée
Une clé qui expire est une clé qui ne traîne pas indéfiniment dans un vieux script.
Créer une clé
Ouvrez la section Clés API
Rendez-vous dans Paramètres → Développeur, puis sélectionnez le sous-onglet Clés API.
Capture à venir
La section Clés API dans les paramètres
Cliquez sur Créer une clé
Une fenêtre Créer une clé API s'ouvre.
Donnez un nom à la clé
Le nom sert à votre suivi et reste visible uniquement par les administrateurs de votre espace. Choisissez un nom qui dit à quoi la clé sert, par exemple « Intégration Make », « Script export mensuel » ou « CRM interne ».
Cochez les autorisations
Sélectionnez le plus petit ensemble d'autorisations nécessaire. Le détail est expliqué plus bas.
Choisissez la durée de validité
Le champ Expire après propose 7 jours, 30 jours, 90 jours, 1 an ou Jamais.
Générez la clé
Cliquez sur Générer la clé. La clé complète s'affiche une seule fois. Copiez-la immédiatement et rangez-la en lieu sûr.
La clé complète n'est affichée qu'au moment de sa création. Elle ne sera plus jamais visible ensuite. Si vous la perdez, révoquez-la et créez-en une nouvelle.
Choisir les autorisations
Les autorisations, ou scopes, se lisent facilement. Elles ont toutes la même forme : une action, deux-points, une base de données.
read:apprenantsautorise à lister et lire les apprenants.write:apprenantsautorise à créer, modifier et supprimer les apprenants.
Les autorisations couvrent les sept bases de la section Mes données.
| Base | Lecture | Écriture |
|---|---|---|
| Apprenants | read:apprenants | write:apprenants |
| Entreprises | read:entreprises | write:entreprises |
| Intervenants | read:intervenants | write:intervenants |
| Lieux | read:lieux | write:lieux |
| Financeurs | read:financeurs | write:financeurs |
| Établissements | read:etablissements | write:etablissements |
| Maîtres d'apprentissage | read:maitres-apprentissage | write:maitres-apprentissage |
Les autorisations d'écriture sont signalées par la mention Destructif dans l'interface. Elles permettent la suppression de données. Ne les accordez qu'aux clés qui en ont vraiment besoin.
Un script qui exporte vos apprenants vers un tableur n'a besoin que de
read:apprenants. Une seule case cochée, et le risque est minimal.
Le pied de la fenêtre rappelle en permanence le nombre d'autorisations sélectionnées. Vous ne pouvez pas générer une clé sans nom ni sans au moins une autorisation.
Utiliser votre clé
Une clé Workbots commence par wb_live_. Elle s'utilise comme un jeton
d'authentification : votre script l'envoie dans l'en-tête Authorization de chaque
requête.
curl https://app.workbots.io/api/... \
-H "Authorization: Bearer wb_live_votre_cle_ici"En Node.js, le principe est le même.
const reponse = await fetch("https://app.workbots.io/api/...", {
headers: {
Authorization: `Bearer ${process.env.WORKBOTS_API_KEY}`,
},
});
const donnees = await reponse.json();La liste des routes disponibles, leurs paramètres et leurs réponses seront publiés dans cette documentation à l'ouverture de l'API. Les exemples ci-dessus illustrent le mode d'authentification, pas un catalogue de routes.
N'écrivez jamais la clé en clair dans votre code. Rangez-la dans une variable
d'environnement, comme WORKBOTS_API_KEY ci-dessus, et n'ajoutez jamais le fichier
qui la contient à votre dépôt de code.
Suivre vos clés
Le tableau des clés affiche quatre colonnes.
| Colonne | Ce qu'elle affiche |
|---|---|
| Nom | Le nom que vous avez choisi, et la date de création en dessous |
| Clé | Le début et la fin de la clé, par exemple wb_live_8a2f…c91d |
| Autorisations | Le nombre d'autorisations accordées |
| Dernière utilisation | Le temps écoulé depuis le dernier appel |
La colonne Dernière utilisation est votre meilleur outil de ménage. Une clé qui n'a pas servi depuis des mois est une clé à révoquer.
Faire expirer ou révoquer une clé
Deux mécanismes se complètent.
L'expiration est décidée à la création, avec le champ Expire après. Passé le délai, la clé cesse d'être acceptée, sans aucune action de votre part.
| Durée | Quand la choisir |
|---|---|
| 7 jours | Un test, une intervention ponctuelle d'un prestataire |
| 30 jours | Une intégration en cours de mise au point |
| 90 jours | Le réglage par défaut, adapté à la plupart des usages |
| 1 an | Une intégration stable, que vous surveillez |
| Jamais | À réserver aux cas où la rotation est impossible |
La révocation est immédiate. Depuis le menu d'actions à droite de la ligne, cliquez sur Révoquer. La clé cesse aussitôt de fonctionner.
La révocation est définitive et prend effet tout de suite. Tout script qui utilisait cette clé s'arrête de fonctionner. Prévoyez la clé de remplacement avant de révoquer.
Révoquez sans hésiter une clé dès que :
- Elle a été partagée par erreur, par message ou par email.
- Elle apparaît dans un dépôt de code public.
- La personne ou le prestataire qui l'utilisait n'intervient plus chez vous.
- Vous constatez des appels que vous n'expliquez pas.