KapsuleHost biedt je twee ontwikkelaarsoppervlakken: API-sleutels met bereik voor het programmatisch lezen van je account, en een externe buildcache die Turborepo en Nx builds op je eigen machines en CI runners versnelt.
Geen van beide is standaard ingeschakeld. Beide worden gemaakt vanuit Instellingen, en beide geven je precies één keer een geheim.
Een API-sleutel maken
API-sleutels bevinden zich onder Instellingen, vervolgens Beveiliging, in de API-sleutels kaart.
- Ga naar Instellingen, vervolgens Beveiliging.
- Scroll naar API-sleutels en klik Nieuwe sleutel.
- Geef de sleutel een naam. Het veld suggereert "Sleutelnaam (bijv. Mijn automatiseringsscript)". De naam is alleen voor jezelf, dus zorg dat het aangeeft waar de sleutel wordt gebruikt.
- Klik op de bereikchips om te selecteren wat de sleutel mag doen. Drie leesreiken zijn voorgeselecteerd:
read:sites,read:emailenread:domains. Klik op een chip om het toe te voegen of te verwijderen. - Klik Maken.
De volledige sleutel verschijnt één keer, in een groen paneel met het opschrift "Kopieer nu". Kopieer het meteen naar je geheime opslag. Wanneer je dat paneel sluit, is de sleutel weg: alleen een korte voorvoegsel wordt bewaard, wat alles is wat de lijst je ooit weer kan tonen.
De sleutel wordt nooit een tweede keer weergegeven en kan niet worden hersteld. Als je het kwijtraakt, trek dan die sleutel in en maak een nieuwe. Plak het niet in een gedeeld document, een ticket, een commit of een chatbericht.
Alleen de rollen Eigenaar en Beheerder kunnen een sleutel maken. Elke andere rol krijgt een machtigingsfout. Wanneer een sleutel wordt gemaakt, gaat er een beveiligingswaarschuwingse-mail naar het adres van degene die deze heeft gemaakt, dus een onverwachte is het onderzoeken waard.
De bereiken
Er worden zeven bereiken aangeboden:
| Bereik | Verleent |
|---|---|
read:sites | Je websites lezen |
write:sites | Gereserveerd voor schrijfbewerkingen op websites |
read:email | Je mailboxen lezen |
write:email | Gereserveerd voor schrijfbewerkingen op mailboxen |
read:domains | Je domeinen lezen |
write:domains | Gereserveerd voor schrijfbewerkingen op domeinen |
read:billing | Gereserveerd voor het lezen van factureringsgegevens |
De klanten-API is vandaag alleen-lezen. De bereiken write: en read:billing kunnen op een sleutel worden geselecteerd, maar geen klanteneindpunt consumeert ze momenteel, dus het toekennen ervan verandert niets. Verleen alleen de leesreiken die je echt nodig hebt en bekijk de sleutel opnieuw wanneer schrijfeindpunten worden uitgebracht.
Een sleutel gebruiken
Stuur de sleutel als dragerstoken op de Authorization koptekst.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Drie eindpunten accepteren een klanten-API-sleutel:
| Eindpunt | Vereist bereik | Retourneert |
|---|---|---|
GET /api/v1/sites | read:sites | Je websites, met domein, toepassingstype en status |
GET /api/v1/domains | read:domains | Je domeinen, met status en vervaldatum |
GET /api/v1/mailboxes | read:email | Je mailboxen |
Een aanvraag zonder sleutel, met een onbekende sleutel of met een ingetrokken sleutel retourneert 401. Een geldige sleutel zonder het juiste bereik retourneert 403 met een bericht dat het benodigde bereik noemt. Elke succesvolle aanroep werkt de tijdstempel van laatst gebruikt van de sleutel bij.
Poll voorzichtig. Deze eindpunten lezen live accountgegevens, en een strakke lus tegen hen is niet te onderscheiden van misbruik. Eenmaal per minuut is royaal voor alles wat een dashboard nodig heeft; eenmaal per uur is meestal meer dan genoeg.
Sleutels controleren en intrekken
De tabel API-sleutels vermeldt elke actieve sleutel op Naam, Voorvoegsel (het zichtbare begin van de sleutel) en Bereiken. Klik Intrekken aan het einde van een rij om het in te schakelen.
Het intrekken werkt onmiddellijk in en er is geen bevestigingsdialoog. De volgende aanvraag met die sleutel mislukt met 401. Een ingetrokken sleutel kan niet worden hersteld, dus zorg ervoor dat je weet wat deze gebruikt voordat je klikt.
Sleutels behoren tot de account, niet tot de persoon die deze heeft gemaakt. Het verwijderen van een teamlid van de teampagina trekt geen sleutels in die zij hebben gemaakt. Bouw een sleutelcontrole in je offboarding: verwijder de persoon en kom hier dan terug en trek alles in wat zij hebben gemaakt.
Het maken en intrekken van sleutels worden beide geregistreerd in het auditlogboek onder de acties api_key.*, met de actor en het oorspronkelijke IP-adres.
De externe buildcache
De pagina Ontwikkelaar, in de geavanceerde groep van de instellingenbalk, biedt een Externe buildcache. Het paneel beschrijft het als een manier om "Turborepo en Nx builds te versnellen door een gedistribueerde cache over machines en CI-pijplijnen te delen."
- Ga naar Instellingen, vervolgens Ontwikkelaar.
- Klik Externe cache inschakelen.
- Kopieer het token uit het paneel met het opschrift "Nieuw token gegenereerd. Kopieer het nu, het wordt niet meer weergegeven".
Stel vervolgens twee omgevingsvariabelen in je CI-configuratie of lokale .env.local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
De team-ID is je KapsuleHost account-ID, weergegeven in de instellingsinstructies op dezelfde pagina.
De pagina stelt zijn eigen compatibiliteit: Turborepo 1.x en hoger, Nx 16 en hoger, en elk hulpmiddel dat hetzelfde externe cacheprotocol implementeert. Artefacten worden per account opgeslagen en worden nooit gedeeld tussen accounts.
Twee verdere besturingselementen bevinden zich op de kaart:
- Token roteren geeft een nieuw token uit en invalideert het oude. Elke CI-taak die het oude token nog vasthoudt, stopt met het gebruik van de cache, dus roteren en werk uw geheimen tegelijk bij.
- Uitschakelen zet de cache helemaal uit.
Tussen de twee kiezen
Ze lossen niet-gerelateerde problemen op en zijn niet uitwisselbaar.
Gebruik een API-sleutel wanneer iets buiten KapsuleHost de toestand van je account moet weten: een statusbord met je sites, een script dat je waarschuwt voor binnenkort vervallende domeinen, een inventarisexport.
Gebruik de externe buildcache wanneer je builds traag zijn omdat elke machine en elke CI-run dezelfde ongewijzigde pakketten opnieuw bouwt. Het heeft niets te maken met je gehoste sites en leest je accountgegevens niet.
Probleemoplossing
Elke aanvraag retourneert 401. Bevestig dat je de koptekst als Authorization: Bearer <key> met één spatie hebt verzonden, dat de sleutel niet is afgekapt toen je deze kopieerde, en dat deze niet is ingetrokken. Vergelijk het begin van je sleutel met de kolom Voorvoegsel om er zeker van te zijn dat je de sleutel gebruikt die je denkt.
Een aanvraag retourneert 403 met een bereik. De sleutel draagt dat bereik niet. Bereiken worden vast ingesteld wanneer de sleutel wordt gemaakt, dus maak een vervanging met de juiste bereiken en trek de oude in.
Ik kan de kaart API-sleutels niet zien. Het bevindt zich op de beveiligingspagina, niet op de ontwikkelaarspagina. De ontwikkelaarspagina bevat alleen de buildcache.
De knop Nieuwe sleutel doet niets. Je rol is lager dan Beheerder. Vraag de Eigenaar of een Beheerder.
Builds gebruiken de cache niet. Controleer of beide TURBO_TOKEN en TURBO_TEAM aanwezig zijn in de buildmilieu, dat het token niet is geroteerd sinds je het hebt ingesteld, en dat de pagina nog steeds het badge Actief toont.
Een sleutel die ik niet heb gemaakt, is verschenen. Behandel het als een compromis. Trek het in en werk vervolgens de Accountbeveiliging door en controleer het auditlogboek voor wat anders is veranderd.