Account
API-sleutels en ontwikkelaarstoegang
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 biedt u twee ontwikkelaarsoppervlakken: scoped API-sleutels voor het programmatisch lezen van uw account, en een externe buildcache die Turborepo- en Nx-builds op uw eigen machines en CI-runners versnelt.
Geen van beide is standaard ingeschakeld. Beide worden aangemaakt via Settings, en beide geven u een geheim exact één keer.
Een API-sleutel aanmaken
API-sleutels bevinden zich onder Settings, dan Security, in de API Keys-kaart.
- Ga naar Settings, dan Security.
- Scroll naar API Keys en klik New key.
- Geef de sleutel een naam. Het veld suggereert "Key name (e.g. My automation script)". De naam is alleen voor u, dus zorg ervoor dat het aangeeft waar de sleutel zal worden gebruikt.
- Klik op de scopechips om te selecteren wat de sleutel mag doen. Drie leesscopes zijn voorgeselecteerd:
read:sites,read:email, enread:domains. Klik op een chip om deze toe te voegen of te verwijderen. - Klik Create.
De volledige sleutel verschijnt eenmaal in een groen paneel met de titel "Copy now". Kopieer deze direct naar uw geheimenopslag. Wanneer u dat paneel verwijdert, is de sleutel weg: alleen een korte voorvoegsel blijft behouden, wat alles is wat de lijst u ooit opnieuw kan tonen.
De sleutel wordt nooit een tweede keer weergegeven en kan niet worden hersteld. Als u deze verliest, trekt u die sleutel in en maakt u een nieuwe. Plak deze niet in een gedeeld document, ticket, commit of chatbericht.
Alleen de rollen Owner en Admin kunnen een sleutel aanmaken. Elke andere rol krijgt een machtigingsfout. Wanneer een sleutel wordt aangemaakt, gaat er een beveiligingswaarschuwingse-mail naar het adres van degene die deze heeft aangemaakt, dus een onverwachte is het waard om onmiddellijk te onderzoeken.
De Scopes
Er worden zeven scopes aangeboden:
| Scope | Verleent |
|---|---|
read:sites | Lezen van uw websites |
write:sites | Gereserveerd voor schrijfbewerkingen op websites |
read:email | Lezen van uw mailboxen |
write:email | Gereserveerd voor schrijfbewerkingen op mailboxen |
read:domains | Lezen van uw domeinen |
write:domains | Gereserveerd voor schrijfbewerkingen op domeinen |
read:billing | Gereserveerd voor het lezen van factureringsgegevens |
De klanten-API is vandaag alleen-lezen. De scopes write: en read:billing kunnen op een sleutel worden geselecteerd, maar geen enkel klanteneindpunt gebruikt deze momenteel, dus deze verlenen verandert niets. Verleen alleen de leesscopes die u werkelijk nodig hebt en herzie de sleutel wanneer schrijfeindpunten worden verzonden.
Een sleutel gebruiken
Stuur de sleutel als een dragertoken op de Authorization header.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Drie eindpunten accepteren een klanten-API-sleutel:
| Eindpunt | Vereiste scope | Retourneert |
|---|---|---|
GET /api/v1/sites | read:sites | Uw websites, met domein, applicatietype en status |
GET /api/v1/domains | read:domains | Uw domeinen, met status en vervaldatum |
GET /api/v1/mailboxes | read:email | Uw mailboxen |
Een verzoek zonder sleutel, met een onbekende sleutel of een ingetrokken sleutel retourneert 401. Een geldige sleutel zonder de juiste scope retourneert 403 met een bericht dat de benodigde scope noemt. Elke succesvolle aanroep werkt het tijdstempel van de laatste keer gebruikt van de sleutel bij.
Poll voorzichtig. Deze eindpunten lezen liveaccountgegevens, en een strakke lus ertegenaan is niet te onderscheiden van misbruik. Eenmaal per minuut is ruim voor alles wat een dashboard nodig heeft; eenmaal per uur is meestal meer dan genoeg.
Sleutels controleren en intrekken
De tabel API Keys geeft elke actieve sleutel weer op Name, Prefix (het zichtbare begin van de sleutel) en Scopes. Klik Revoke aan het einde van een rij om deze uit te schakelen.
Intrekken wordt onmiddellijk van kracht en er is geen bevestigingsdialoog. Het volgende verzoek met die sleutel mislukt met 401. Een ingetrokken sleutel kan niet worden hersteld, dus zorg ervoor dat u weet wat deze gebruikt voordat u klikt.
Sleutels behoren tot het account, niet tot de persoon die deze heeft aangemaakt. Het verwijderen van een teamlid van the Team page trekt de sleutels die zij hebben gemaakt niet in. Bouw een sleutelcontrole in uw offboarding: verwijder de persoon en kom hier dan terug om alles wat zij hebben aangemaakt in te trekken.
Sleutelaanmaak en intrekking worden beide vastgelegd in the audit log onder de acties api_key.*, met de actor en het afkomstige IP-adres.
De externe buildcache
De pagina Developer, in de groep Advanced van de instellingenbalk, biedt een Remote Build Cache. Het paneel beschrijft dit als een manier om "Turborepo- en Nx-builds te versnellen door een gedistribueerde cache over machines en CI-pijplijnen heen te delen."
- Ga naar Settings, dan Developer.
- Klik Enable remote cache.
- Kopieer het token uit het paneel getiteld "New token generated. Copy it now, it won't be shown again".
Stel vervolgens twee omgevingsvariabelen in in uw CI-configuratie of lokale .env.local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
De team-ID is uw Kapsule-account-ID, weergegeven in de setup-instructies op dezelfde pagina.
De pagina vermeldt zijn eigen compatibiliteit: Turborepo 1.x en later, Nx 16 en later, en elk hulpmiddel dat hetzelfde externe cacheprotocol implementeert. Artefacten worden per account opgeslagen en worden nooit over accounts heen gedeeld.
Twee verdere besturingselementen bevinden zich op de kaart:
- Rotate token geeft een nieuw token uit en maakt het oude ongeldig. Elke CI-taak die nog steeds het oude token bevat, stopt met het gebruiken van de cache, dus roteer en werk uw geheimen tegelijk bij.
- Disable schakelt de cache helemaal uit.
Kiezen tussen de twee
Zij lossen onafhankelijke problemen op en zijn niet uitwisselbaar.
Gebruik een API key wanneer iets buiten Kapsule de status van uw account moet kennen: een statusbord dat uw sites opsomt, een script dat u waarschuwt voor domeinen die binnenkort verlopen, een inventarisexport.
Gebruik de remote build cache wanneer uw builds traag zijn omdat elke machine en elke CI-run dezelfde ongewijzigde pakketten opnieuw bouwt. Het heeft niets te maken met uw gehoste sites en leest uw accountgegevens niet.
Als u implementeert vanuit Git in plaats van een API aan te roepen, kijk dan naar Orbit. Het bouwt en verzend vanuit uw repository rechtstreeks, met buildcaching die voor u wordt afgehandeld.
Probleemoplossing
Elk verzoek retourneert 401. Bevestig dat u de header als Authorization: Bearer <key> met een spatie hebt verzonden, dat de sleutel niet is afgekapt toen u deze kopieerde, en dat deze niet is ingetrokken. Vergelijk het begin van uw sleutel met de kolom Prefix om zeker te weten dat u de sleutel gebruikt die u denkt.
Een verzoek retourneert 403 en noemt een scope. De sleutel draagt die scope niet. Scopes worden vastgesteld wanneer de sleutel wordt aangemaakt, dus maak een vervanger met de juiste scopes en trek de oude in.
Ik kan de API Keys-kaart niet zien. Deze bevindt zich op de pagina Security, niet op de pagina Developer. De pagina Developer bevat alleen de buildcache.
De knop New key doet niets. Uw rol is onder Admin. Vraag de Owner of een Admin.
Builds raken de cache niet. Controleer of beide TURBO_TOKEN en TURBO_TEAM aanwezig zijn in de buildomgeving, dat het token niet is geroteerd sinds u het hebt ingesteld, en dat de pagina nog steeds het badge Active toont.
Een sleutel die ik niet heb aangemaakt, verscheen. Behandel dit als een inbreuk. Trek het in en werk dan Account Security door en controleer the audit log op wat anders is veranderd.