Compte
Clés API et accès développeur
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
Kapsule vous offre deux surfaces de développeur : des clés API limitées en portée pour lire votre compte par programme, et un cache de compilation distant qui accélère les builds Turborepo et Nx sur vos machines et vos exécuteurs CI.
Aucun des deux n'est activé par défaut. Les deux sont créés à partir de Paramètres, et les deux vous remettent un secret exactement une fois.
Créer une clé API
Les clés API se trouvent dans Paramètres, puis Sécurité, dans la carte Clés API.
- Allez dans 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 la clé (ex. Mon script d'automatisation) ». Le nom n'est que pour vous, alors faites-le indiquer 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:email, etread: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 avec l'en-tête « Copier maintenant ». Copiez-la directement dans votre gestionnaire de secrets. Quand vous fermez ce panneau, la clé a disparu : seul un court préfixe est conservé, c'est tout ce que la liste peut 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 obtient une erreur de permissions. Quand une clé est créée, un email d'alerte de sécurité est envoyé à l'adresse de celui qui l'a créée, donc une inattendue vaut la peine d'être examinée immédiatement.
Les portées
Sept portées sont proposées :
| 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. Accordez uniquement les portées de lecture que vous avez réellement besoin et revisitez la clé quand les points de terminaison d'écriture seront disponibles.
Utiliser une clé
Envoyez la clé comme un jeton bearer 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 expiration |
GET /api/v1/mailboxes | read:email | Vos boîtes aux lettres |
Une requête sans clé, avec une clé inconnue, ou avec 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 doucement. 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 tout ce qu'un tableau de bord doit faire ; une fois par heure est généralement plus que suffisant.
Examiner et révoquer les clés
Le tableau Clés API répertorie 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, donc assurez-vous de savoir ce qui l'utilise avant de cliquer.
Les clés appartiennent au compte, et non à 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 dans votre offboarding : supprimez la personne, puis venez ici et révoquez tout ce qu'elle a créé.
La création et la révocation des 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 compilation distant
La page Développeur, dans le groupe Avancé du rail de paramètres, propose un Cache de compilation distant. Le panneau le décrit comme un moyen « d'accélérer les builds Turborepo et Nx en partageant un cache distribué entre machines et pipelines CI ».
- Allez dans 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 plus affiché ».
Puis définissez deux variables d'environnement dans votre configuration CI ou votre .env.local local :
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
L'ID d'équipe est votre ID de compte Kapsule, 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 comptes.
Deux autres contrôles se trouvent sur la carte :
- Faire pivoter le 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 pivoter et mettez à jour vos secrets ensemble.
- Désactiver désactive complètement le cache.
Choisir entre les deux
Ils résolvent des problèmes sans lien et ne sont pas interchangeables.
Utilisez une clé API quand quelque chose en dehors de Kapsule a besoin de connaître l'état de votre compte : un tableau de bord qui liste vos sites, un script qui vous avertit des domaines expirés bientôt, une exportation d'inventaire.
Utilisez le cache de compilation distant quand vos builds sont lents parce que chaque machine et chaque exécution CI reconstruisent les mêmes paquets inchangés. Il n'a rien à voir avec vos sites hébergés et ne lit pas vos données de compte.
Si vous déployez à partir de Git plutôt que d'appeler une API, regardez Kapsule Orbit à la place. Il crée et expédie à partir de votre référentiel directement, avec la mise en cache des builds gérée pour vous.
Dépannage
Chaque requête retourne 401. Confirmez que vous avez envoyé l'en-tête comme 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 fixées 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 sur la page Développeur. La page Développeur contient seulement le cache de compilation.
Le bouton Nouvelle clé ne fait rien. Votre rôle est inférieur à Admin. Demandez au Propriétaire ou à un Admin.
Les builds ne frappent pas le cache. Vérifiez que TURBO_TOKEN et TURBO_TEAM sont tous deux présents dans l'environnement de compilation, que le jeton n'a pas été fait pivoter 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 a 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é.