KapsuleHost vous offre deux surfaces de développement : des clés API avec portées pour lire votre compte par programmation, et un cache de construction à distance qui accélère les constructions Turborepo et Nx sur vos propres machines et exécuteurs CI.
Aucun n'est activé par défaut. Les deux sont créés à partir de Paramètres, et tous les deux vous remettent un secret exactement une fois.
Créer une clé API
Les clés API se trouvent sous Paramètres, puis Sécurité, dans la carte Clés API.
- Allez à Paramètres, puis Sécurité.
- Faites défiler jusqu'à Clés API et cliquez sur Nouvelle clé.
- Donnez un nom à la clé. Le champ suggère « Nom de clé (par ex. Mon script d'automatisation) ». Le nom est seulement pour vous, alors faites en sorte qu'il indique où la clé sera utilisée.
- Cliquez sur les puces de portée pour sélectionner ce que la clé peut faire. Trois portées de lecture sont présélectionnées :
read:sites,read:emailetread:domains. Cliquez sur une puce pour l'ajouter ou la retirer. - Cliquez sur Créer.
La clé complète apparaît une seule fois, dans un panneau vert intitulé « Copier maintenant ». Copiez-la directement dans votre magasin de secrets. Quand vous fermez ce panneau, la clé disparaît : seul un court préfixe est conservé, c'est tout ce que la liste pourra jamais vous montrer à nouveau.
La clé n'est jamais affichée une deuxième fois et ne peut pas être récupérée. Si vous la perdez, révoquez cette clé et créez-en une nouvelle. Ne la collez pas dans un document partagé, un ticket, un commit ou un message de chat.
Seuls les rôles Propriétaire et Admin peuvent créer une clé. Tout autre rôle reçoit une erreur de permissions. Quand une clé est créée, un e-mail d'alerte de sécurité est envoyé à l'adresse de celui qui l'a créée, alors une alerte inattendue de ce type vaut la peine d'être enquêtée immédiatement.
Les portées
Sept portées sont offertes :
| Portée | Accorde |
|---|---|
read:sites | Lecture de vos sites web |
write:sites | Réservé aux opérations d'écriture sur les sites web |
read:email | Lecture de vos boîtes aux lettres |
write:email | Réservé aux opérations d'écriture sur les boîtes aux lettres |
read:domains | Lecture de vos domaines |
write:domains | Réservé aux opérations d'écriture sur les domaines |
read:billing | Réservé à la lecture des données de facturation |
L'API client est actuellement en lecture seule. Les portées write: et read:billing peuvent être sélectionnées sur une clé, mais aucun point de terminaison client ne les consomme actuellement, donc les accorder ne change rien. N'accordez que les portées de lecture dont vous avez réellement besoin et réexaminez la clé quand les points de terminaison d'écriture seront disponibles.
Utiliser une clé
Envoyez la clé comme jeton porteur sur l'en-tête Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Trois points de terminaison acceptent une clé API client :
| Point de terminaison | Portée requise | Retourne |
|---|---|---|
GET /api/v1/sites | read:sites | Vos sites web, avec domaine, type d'application et statut |
GET /api/v1/domains | read:domains | Vos domaines, avec statut et date d'expiration |
GET /api/v1/mailboxes | read:email | Vos boîtes aux lettres |
Une requête sans clé, avec une clé inconnue ou une clé révoquée retourne 401. Une clé valide sans la bonne portée retourne 403 avec un message nommant la portée qui était nécessaire. Chaque appel réussi met à jour l'horodatage de dernière utilisation de la clé.
Interrogez avec modération. Ces points de terminaison lisent les données de compte en direct, et une boucle serrée contre eux est indiscernable d'un abus. Une fois par minute est généreux pour n'importe quoi dont un tableau de bord a besoin ; une fois par heure est généralement suffisant.
Examiner et révoquer des clés
La table Clés API liste chaque clé active par Nom, Préfixe (le début visible de la clé) et Portées. Cliquez sur Révoquer à la fin d'une ligne pour la désactiver.
La révocation prend effet immédiatement et il n'y a pas de dialogue de confirmation. La requête suivante utilisant cette clé échoue avec 401. Une clé révoquée ne peut pas être restaurée, alors assurez-vous de savoir ce qui l'utilise avant de cliquer.
Les clés appartiennent au compte, pas à la personne qui les a créées. Retirer un coéquipier de la page Équipe ne révoque pas les clés qu'il a créées. Intégrez un examen des clés à votre offboarding : retirez la personne, puis venez ici et révoquez tout ce qu'elle a créé.
La création et la révocation de clés sont toutes deux enregistrées dans le journal d'audit sous les actions api_key.*, avec l'acteur et l'adresse IP d'origine.
Le cache de construction à distance
La page Développeur, dans le groupe Avancé du rail des paramètres, offre un Cache de construction à distance. Le panneau le décrit comme un moyen « d'accélérer les constructions Turborepo et Nx en partageant un cache distribué sur les machines et les pipelines CI ».
- Allez à Paramètres, puis Développeur.
- Cliquez sur Activer le cache distant.
- Copiez le jeton du panneau intitulé « Nouveau jeton généré. Copiez-le maintenant, il ne sera pas affiché à nouveau ».
Définissez ensuite deux variables d'environnement dans votre configuration CI ou .env.local local :
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
L'ID d'équipe est votre ID de compte KapsuleHost, affiché dans les instructions de configuration sur la même page.
La page énonce sa propre compatibilité : Turborepo 1.x et versions ultérieures, Nx 16 et versions ultérieures, et tout outil implémentant le même protocole de cache distant. Les artefacts sont stockés par compte et ne sont jamais partagés entre les comptes.
Deux contrôles supplémentaires se trouvent sur la carte :
- Rotation du jeton émet un nouveau jeton et invalide l'ancien. Tout travail CI détenant toujours l'ancien jeton cesse d'utiliser le cache, alors faites tourner et mettez à jour vos secrets ensemble.
- Désactiver éteint complètement le cache.
Choisir entre les deux
Ils résolvent des problèmes non liés et ne sont pas interchangeables.
Utilisez une clé API quand quelque chose en dehors de KapsuleHost a besoin de connaître l'état de votre compte : un tableau de statut qui liste vos sites, un script qui vous avertit à propos des domaines expirant bientôt, une exportation d'inventaire.
Utilisez le cache de construction à distance quand vos constructions sont lentes parce que chaque machine et chaque exécution CI reconstruisent les mêmes packages inchangés. Cela n'a rien à voir avec vos sites hébergés et ne lit pas vos données de compte.
Dépannage
Chaque requête retourne 401. Confirmez que vous avez envoyé l'en-tête en tant que Authorization: Bearer <key> avec un seul espace, que la clé n'a pas été tronquée quand vous l'avez copiée, et qu'elle n'a pas été révoquée. Comparez le début de votre clé avec la colonne Préfixe pour vous assurer que vous utilisez la clé que vous pensez utiliser.
Une requête retourne 403 en nommant une portée. La clé ne porte pas cette portée. Les portées sont fixes quand la clé est créée, alors créez un remplacement avec les bonnes portées et révoquez l'ancienne.
Je ne peux pas voir la carte Clés API. Elle est sur la page Sécurité, pas la page Développeur. La page Développeur ne contient que le cache de construction.
Le bouton Nouvelle clé ne fait rien. Votre rôle est inférieur à Admin. Demandez au Propriétaire ou à un Admin.
Les constructions ne touchent pas le cache. Vérifiez que TURBO_TOKEN et TURBO_TEAM sont tous deux présents dans l'environnement de construction, que le jeton n'a pas été pivoté depuis que vous l'avez défini, et que la page affiche toujours le badge Actif.
Une clé que je n'ai pas créée est apparue. Traitez-la comme une compromission. Révoquez-la, puis travaillez à travers Sécurité du compte et vérifiez le journal d'audit pour voir ce qui d'autre a changé.