Gestion des clés API

Les clés API donnent un accès programmatique à l'API publique /v1/*. Chaque clé porte une liste explicite de capacités -- les routes qu'elle peut appeler -- pour limiter les dégâts si une clé fuit un jour. Créez autant de clés que nécessaire, une par intégration, et restreignez chacune au strict minimum.

Créer une clé#

1. Connectez-vous au tableau de bord.
2. Ouvrez /settings?tab=apiKeys.
3. Cliquez sur le bouton de création.
4. Donnez à la clé un nom descriptif -- "CI production", "Monitoring staging", "Client MCP local" -- pour la reconnaître plus tard.
5. Choisissez les capacités nécessaires à l'intégration. Le formulaire coche par défaut desktop:read et desktop:chat, ce qui suffit pour lister les bureaux et envoyer des messages. N'ajoutez d'autres capacités que si l'intégration en a vraiment besoin.
6. Copiez la clé tout de suite. Elle n'est affichée en clair qu'une seule fois. Ne committez JAMAIS la clé dans un dépôt.

La valeur ressemble à sk_live_.... SpineOS stocke un hash bcrypt, pas la version en clair, donc la clé est irrécupérable après coup. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Utiliser une clé#

Envoyez la clé dans l'en-tête Authorization. L'appel le moins coûteux pour vérifier que tout est branché correctement est /v1/me :

curl https://www.spinestudio.dev/v1/me \
  -H "Authorization: Bearer sk_live_..."

La réponse contient l'id utilisateur, l'email, le rôle, le tier, et les capacités de la clé utilisée pour la requête -- pratique pour confirmer que la clé a bien les portées attendues.

Capacités#

Chaque clé porte une liste de routes qu'elle est autorisée à appeler. Le défaut à la création est volontairement restreint : desktop:read et desktop:chat. Tout ce qui va plus loin -- démarrer et arrêter des bureaux, envoyer des entrées de contrôle, tâches planifiées, lecture de la base de connaissances -- doit être coché explicitement.

Les capacités sont statiques. Il n'y a pas de flux d'édition de clé. Pour changer les portées d'une clé, révoquez-la et recréez-en une nouvelle avec les bonnes cases cochées. Voir Capacités API pour la liste complète et ce que chaque capacité débloque.

Lister, faire tourner, révoquer#

Toute la gestion des clés se passe sur /settings?tab=apiKeys. La page liste chaque clé active avec son nom, sa date de création et ses capacités. Cette version n'expose pas d'API publique pour lister ou révoquer les clés par programme.

Pour faire tourner une clé sans interruption : créez d'abord la nouvelle, basculez l'intégration, vérifiez que tout fonctionne, puis révoquez l'ancienne.

En cas de fuite#

Révoquez immédiatement la clé sur /settings?tab=apiKeys. La révocation est effective tout de suite -- toute requête utilisant la clé révoquée renvoie 401. Recréez ensuite une clé avec les mêmes capacités et basculez l'intégration sur la nouvelle valeur. Si vous soupçonnez que la clé a été utilisée pour quelque chose d'inattendu, vérifiez l'activité récente sur les ressources concernées.

Recommandations#