L'API SystemBuddy

Un autre système peut lire et écrire une tranche étroite et délibérée de SystemBuddy par HTTPS : les billets, les actifs et les articles de connaissances publiés. Il s'authentifie avec une clé d'API, qui est une identité de service et jamais une personne. Les clés sont créées par un administrateur dans Administration, Clés d'API.

1 · S'authentifier

Chaque appel porte la clé dans un en-tête. Les deux formes suivantes sont acceptées :

• X-Api-Key: sbk_3f9a1c40_...
• Authorization: ApiKey sbk_3f9a1c40_...

Une clé ressemble à sbk_3f9a1c40_<aléatoire>. Les deux premiers segments forment le préfixe. Le préfixe est public : c'est lui que la liste des clés, les journaux et la piste d'audit utilisent pour nommer une clé, alors on peut le citer sans risque dans une conversation de soutien. Le reste est le secret.

La clé n'est montrée qu'une seule fois, sur l'écran qui la crée. SystemBuddy n'en conserve qu'une empreinte SHA-256, de sorte que personne, nous y compris, ne peut l'afficher de nouveau. Si elle est perdue ou divulguée, révoquez-la et créez-en une autre.

2 · Portées

Une clé porte les portées nommées qu'un administrateur a cochées, et rien d'autre. Un appel à un point d'accès dont la clé n'a pas la portée est refusé avec un 403, et le refus est inscrit dans la piste d'audit.

• tickets:read, lire les billets de l'organisation de la clé.
• tickets:write, créer des billets et ajouter des commentaires publics au nom d'un compte existant de cette organisation.
• assets:read, lire l'inventaire des actifs.
• assets:write, mettre à jour l'emplacement, le bâtiment, le local, le statut et les notes d'un actif.
• knowledge:read, lire les articles publiés de la base de connaissances.

Donnez à une clé le minimum dont elle a besoin. Une tâche de production de rapports veut généralement tickets:read et rien de plus.

3 · Ce qu'une clé ne peut jamais faire

C'est la partie qui compte, alors elle mérite d'être dite clairement. Une clé est authentifiée par son propre mécanisme, distinct de celui avec lequel les gens se connectent, et l'entité qu'elle produit ne porte aucune identité d'utilisateur : aucun identifiant d'utilisateur, aucun rôle, aucun groupe, aucune permission héritée. Aucune portée n'accorde l'un des éléments suivants, et aucun point d'accès qui les offre n'accepte une clé :

• Exécuter des scripts, pousser des installations ou des désinstallations, ou toute autre action de l'agent sur un poste.
• Isoler, verrouiller, effacer ou mettre hors service un appareil.
• Créer, modifier, désactiver ou élever un utilisateur, un rôle ou une clé d'API.
• Lire ou écrire des dossiers RH, et en particulier tout champ sensible d'un employé.
• Les paramètres, les licences, la piste d'audit, l'exposition de sécurité, l'accès d'urgence, ou tout autre geste qu'un administrateur pose de façon interactive.

Ces points d'accès répondent 401 à une clé, exactement comme ils le font en l'absence totale d'identifiant. Une suite de tests négatifs rejoue chaque point d'accès privilégié du produit avec une clé active et de pleine portée à chaque compilation, et échoue si un seul renvoie une réussite.

4 · Limites de débit

Chaque clé a sa propre limite de requêtes par minute, définie à sa création et modifiable par la suite. Elle est appliquée par clé, et non par adresse, de sorte qu'une intégration très active ne peut pas dépenser le budget d'une autre.

• Les réponses réussies portent X-RateLimit-Limit et X-RateLimit-Remaining.
• Au-delà de la limite, l'API répond 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre. Respectez-le : réessayer plus tôt ne fait que dépenser la fenêtre suivante.
• Le premier refus d'une fenêtre est consigné, de sorte qu'un administrateur repère une clé constamment au-delà de son budget sans que la piste d'audit se remplisse.

Le serveur applique aussi sa propre limite par adresse devant tout le reste, et le mandataire inverse d'un client peut en ajouter une troisième. Si vous êtes ralenti et qu'aucun Retry-After n'est présent, c'est la bordure qui vous limite, et non la clé.

5 · Expiration et révocation

Une clé a une date d'expiration, proposée à 90 jours et réglable jusqu'à deux ans. Une clé expirée cesse de fonctionner d'elle-même, et c'est le but : une intégration que plus personne ne possède s'éteint discrètement au lieu de vivre éternellement.

La révocation est immédiate. Dès qu'un administrateur révoque une clé, l'appel suivant qui la présente est refusé, et le refus, avec son motif, figure dans la piste d'audit. La création, la modification et la révocation d'une clé sont elles aussi consignées, par préfixe et jamais par la clé elle-même.

La liste des clés indique, pour chaque clé, sa dernière utilisation et l'adresse d'où elle provient, ainsi que le nombre d'appels servis. C'est le moyen le plus rapide de répondre à « est-ce que quelque chose s'en sert encore ? » avant de la désactiver.

6 · La description de l'API

Chaque serveur SystemBuddy publie un document OpenAPI 3.0 correspondant exactement à la surface qu'une clé peut atteindre, à /api/v1/openapi.json sur ce serveur. Il est généré à partir du code en cours d'exécution, alors il décrit ce que cette version sert réellement, y compris la portée requise pour chaque opération. Dirigez-y votre générateur de client.

Les points d'accès sous /api/v1 aujourd'hui :

• GET /api/v1/me, ce qu'est cette clé : préfixe, organisation et portées. Utile comme vérification de connectivité.
• GET /api/v1/tickets et GET /api/v1/tickets/{id}, paginés, les plus récents d'abord.
• POST /api/v1/tickets, créer un billet pour un demandeur nommé qui a déjà un compte.
• POST /api/v1/tickets/{id}/comments, ajouter un commentaire public au nom d'un compte existant.
• GET /api/v1/assets et GET /api/v1/assets/{id}.
• PATCH /api/v1/assets/{id}, champs d'inventaire seulement.
• GET /api/v1/knowledge/articles, articles publiés seulement.

Les listes acceptent page et pageSize. pageSize est plafonné à 200, alors demandez des pages plutôt que tout d'un coup.

7 · Réponses à gérer

• 200, le corps est {"success":true,"data":...}.
• 400, le corps a été rejeté et le message nomme le champ. Les champs inconnus sont refusés plutôt qu'ignorés.
• 401, la clé est absente, mal formée, inconnue, révoquée ou expirée.
• 403, la clé ne porte pas la portée requise par ce point d'accès.
• 404, aucun enregistrement de ce type dans l'organisation de cette clé. Un enregistrement appartenant à une autre organisation donne un 404, et non un 403 : une clé ne peut pas apprendre qu'il existe.
• 429, au-delà de la limite de débit de la clé. Attendez la valeur de Retry-After.

Des questions ?

Écrivez à orders@systembuddy.net avec le préfixe de la clé que vous utilisez, jamais la clé elle-même, et ce que vous cherchez à bâtir.