Les clés API

Une clé API sert à faire travailler un programme à votre place : un script qui ouvre une commande quand un formulaire de votre site est rempli, un tableau de bord qui compte vos commandes du mois, un outil que vous écrivez vous-même.

Si vous ne programmez pas et ne faites appel à personne qui programme, vous n'avez aucune raison d'en créer une. Rien dans Kalepio n'en a besoin.

Où elles se trouvent

Dans Paramètres, Clés API. Dans vos réglages personnels, et pas dans ceux du studio, parce qu'une clé vous appartient : c'est vous qui l'avez créée, et elle disparaît de vos studios en même temps que vous.

Une clé, un studio

Au moment de créer une clé, vous choisissez le studio dans lequel elle travaillera. Elle ne pourra jamais rien faire ailleurs, même si vous êtes dans dix autres studios.

C'est ce qui rend une clé raisonnable à confier : si elle se retrouve entre de mauvaises mains, ce qui est en jeu est un atelier, pas tout votre travail.

Une clé ne fait jamais plus que vous

C'est la règle la plus importante de cet écran, et elle a deux moitiés.

Vous ne pouvez donner que des droits que vous avez déjà. L'écran ne vous propose que ceux-là : si votre studio ne vous laisse pas gérer les paiements, la case n'apparaît pas. Ce n'est pas un oubli, c'est la seule chose que la clé pourrait de toute façon faire.

Et elle suit vos droits dans le temps. Le jour où votre studio vous retire un droit, la clé le perd aussi, sans que personne ait à y penser. Le jour où vous quittez ce studio, elle cesse complètement de fonctionner.

« Tout ce que je peux faire », ou une liste

Deux façons de décider ce qu'une clé pourra faire.

Tout ce que je peux faire est coché par défaut, et c'est ce qu'il faut pour vos propres outils. La clé fait exactement ce que vous faites déjà depuis votre tableau de bord, et elle reste alignée : un droit qu'on vous accorde plus tard, elle l'aura aussi.

Une liste, cochée à la main, quand vous confiez la clé à quelqu'un d'autre ou à un programme que vous n'avez pas écrit. Une clé qui ne sait que lire les commandes ne peut rien supprimer, même si vous, vous le pouvez.

La clé n'est affichée qu'une fois

À la création, dans une fenêtre, avec un bouton pour la copier. Rangez-la tout de suite dans un gestionnaire de mots de passe.

Ensuite, elle n'est plus affichable. Nous n'en gardons qu'une empreinte, comme pour un mot de passe : il n'existe aucun moyen de la retrouver, ni pour vous ni pour nous. Si vous la perdez, révoquez-la et créez-en une autre.

C'est aussi pourquoi le nom que vous lui donnez compte : c'est la seule façon de reconnaître la bonne quand la liste en contient quatre.

Révoquer une clé

Un clic, et elle cesse de fonctionner immédiatement. Tout programme qui s'en servait recevra une erreur à sa requête suivante.

À faire sans hésiter dès qu'une clé a été copiée dans un endroit qu'elle n'aurait pas dû atteindre : une capture d'écran, un message, un fichier de configuration partagé. Créer une nouvelle clé prend dix secondes.

Ce que la liste n'affiche pas

La date de dernière utilisation. Kalepio ne la conserve pas, et son absence n'est pas un bug : c'est une information que nous avons choisi de ne pas garder.

Pour la personne qui va s'en servir

L'adresse de l'API, la liste des requêtes possibles, les filtres et les codes d'erreur sont dans la référence de l'API, qui est écrite en anglais parce qu'elle est lue à côté de noms de classes et de codes HTTP.

Le premier appel à faire est toujours le même : il indique à quel studio la clé appartient et ce qu'elle a exactement le droit d'y faire.