Authentification API
Comment s'authentifier sur l'API REST publique : cookies de session pour Mission Control, clés API en Bearer pour l'accès programmatique.
Il y a deux manières de parler à SpineOS. Le tableau de bord utilise un cookie de session pose à la connexion. Tout le reste -- scripts, jobs CI, intégrations tierces, clients MCP -- utilise une clé API envoyée dans Authorization: Bearer sk_live_.... Chacune a son usage, elles ne sont pas interchangeables.
Cookies de session (tableau de bord uniquement)
Connectez-vous via Google ou GitHub et le tableau de bord reçoit automatiquement un cookie de session sécurisé. Le cookie est httpOnly, limite au domaine SpineOS, et inaccessible depuis JavaScript. Il existe pour que le tableau de bord puisse appeler l'API sans gérer de jeton.
N'essayez pas de réutiliser ce cookie depuis un script, un job CI ou un worker. Il est lié à une session navigateur et n'est pas conçu pour l'accès programmatique. Pour tout ce qui sort du tableau de bord, créez une clé API.
Clés API (accès programmatique)
Envoyez la clé comme jeton Bearer dans l'en-tête Authorization à chaque requête :
curl https://www.spinestudio.dev/v1/desktops \
-H "Authorization: Bearer sk_live_..."
Les clés se gèrent uniquement depuis le tableau de bord, sur /settings?tab=apiKeys -- il n'y a pas d'API pour créer, lister ou révoquer une clé avec une autre clé. Chaque clé commence par sk_live_, est hashée au repos, et n'est affichée en clair qu'une seule fois à la création. Chaque clé porte une liste explicite de capacités qui décide quelles routes elle peut appeler. Voir Capacités API pour la liste complète et comment les choisir.
Limitation de débit
L'API publique autorise 60 requêtes par minute et par clé. Les compteurs sont tenus par clé, pas par IP, donc deux clés distinctes utilisées en parallèle disposent chacune de leurs 60/min. Si une intégration a besoin de plus de marge, répartissez la charge sur plusieurs clés.
Quand la limite est atteinte, la réponse est 429 Too Many Requests. Si l'en-tête Retry-After est présent, attendez ce nombre de secondes avant de réessayer. Sinon, attendez au moins quelques secondes avant l'appel suivant.
Erreurs d'authentification
| Statut | Signification |
|---|---|
401 Unauthorized | L'en-tête Authorization est absent ou mal forme, ou la clé est invalide ou révoquée |
403 Forbidden | La clé est valide mais ne porte pas la capacité requise par la route. Le corps contient required et held -- voir Capacités API |
429 Too Many Requests | Limite de débit atteinte. Respectez Retry-After s'il est présent |
Pratiques de sécurité
- Ne committez jamais une clé dans git, ne la collez pas dans un ticket, ne l'embarquez pas dans du code côté client.
- Faites tourner les clés régulièrement : créez la nouvelle, basculez l'intégration, puis révoquez l'ancienne.
- Une clé par intégration, pour qu'une révocation n'en casse pas d'autres.
- Restreignez chaque clé au minimum de capacités dont l'intégration a vraiment besoin.