KapsuleHost bietet dir zwei Entwickleroberflächen: begrenzte API-Schlüssel zum programmatischen Auslesen deines Kontos und einen Remote-Build-Cache, der Turborepo- und Nx-Builds auf deinen eigenen Computern und CI-Runnern beschleunigt.
Beide sind standardmäßig nicht aktiviert. Beide werden über Einstellungen erstellt und beide geben dir genau einmal ein Geheimnis aus.
API-Schlüssel erstellen
API-Schlüssel befinden sich unter Einstellungen, dann Sicherheit, in der Karte API-Schlüssel.
- Gehe zu Einstellungen, dann Sicherheit.
- Scrolle zu API-Schlüssel und klicke auf Neuer Schlüssel.
- Gib dem Schlüssel einen Namen. Das Feld schlägt "Key name (e.g. My automation script)" vor. Der Name ist nur für dich, daher sollte er angeben, wo der Schlüssel verwendet wird.
- Klicke auf die Scope-Chips, um auszuwählen, was der Schlüssel tun darf. Drei Lesescopes sind vorausgewählt:
read:sites,read:emailundread:domains. Klicke auf einen Chip, um ihn hinzuzufügen oder zu entfernen. - Klicke auf Erstellen.
Der vollständige Schlüssel wird einmalig in einem grünen Panel mit der Überschrift "Copy now" angezeigt. Kopiere ihn sofort in deinen Secret-Speicher. Wenn du dieses Panel schließt, ist der Schlüssel weg: nur ein kurzes Präfix wird beibehalten, das ist alles, was die Liste dir jemals wieder zeigen kann.
Der Schlüssel wird ein zweites Mal nie angezeigt und kann nicht wiederhergestellt werden. Wenn du ihn verlierst, widerrufe diesen Schlüssel und erstelle einen neuen. Füge ihn nicht in ein gemeinsames Dokument, ein Ticket, einen Commit oder eine Chat-Nachricht ein.
Nur die Rollen Owner und Admin können einen Schlüssel erstellen. Jede andere Rolle erhält einen Berechtigungsfehler. Wenn ein Schlüssel erstellt wird, wird eine Sicherheitswarnungs-E-Mail an die Adresse der Person gesendet, die ihn erstellt hat. Eine unerwartete ist es wert, sofort untersucht zu werden.
Die Scopes
Es werden sieben Scopes angeboten:
| Scope | Berechtigung |
|---|---|
read:sites | Lesen deiner Websites |
write:sites | Reserviert für Schreibvorgänge auf Websites |
read:email | Lesen deiner Postfächer |
write:email | Reserviert für Schreibvorgänge auf Postfächern |
read:domains | Lesen deiner Domains |
write:domains | Reserviert für Schreibvorgänge auf Domains |
read:billing | Reserviert für Lesen von Abrechnungsdaten |
Die Kunden-API ist derzeit nur lesbar. Die Scopes write: und read:billing können auf einem Schlüssel ausgewählt werden, aber kein Kunden-Endpoint nutzt sie derzeit, daher hat das Gewähren keine Auswirkungen. Gewähre nur die Lesescopes, die du wirklich brauchst, und überprüfe den Schlüssel erneut, wenn Schreib-Endpoints verfügbar werden.
Einen Schlüssel verwenden
Sende den Schlüssel als Bearer-Token im Header Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Drei Endpoints akzeptieren einen Kunden-API-Schlüssel:
| Endpoint | Erforderlicher Scope | Rückgabe |
|---|---|---|
GET /api/v1/sites | read:sites | Deine Websites mit Domain, Anwendungstyp und Status |
GET /api/v1/domains | read:domains | Deine Domains mit Status und Ablauf |
GET /api/v1/mailboxes | read:email | Deine Postfächer |
Eine Anfrage ohne Schlüssel, mit einem unbekannten Schlüssel oder mit einem widerrufenen Schlüssel gibt 401 zurück. Ein gültiger Schlüssel ohne den richtigen Scope gibt 403 mit einer Nachricht zurück, die den erforderlichen Scope benennt. Jeder erfolgreiche Aufruf aktualisiert den Zeitstempel der letzten Verwendung des Schlüssels.
Frage vorsichtig ab. Diese Endpoints lesen Live-Kontodaten aus, und eine enge Schleife dagegen ist nicht von Missbrauch zu unterscheiden. Einmal pro Minute ist großzügig für alles, was ein Dashboard braucht. Einmal pro Stunde ist normalerweise mehr als ausreichend.
Schlüssel überprüfen und widerrufen
Die Tabelle der API-Schlüssel listet jeden aktiven Schlüssel nach Name, Präfix (der sichtbare Anfang des Schlüssels) und Scopes auf. Klicke auf Widerrufen am Ende einer Zeile, um ihn zu deaktivieren.
Das Widerrufen wird sofort wirksam und es gibt keinen Bestätigungsdialog. Die nächste Anfrage mit diesem Schlüssel schlägt mit 401 fehl. Ein widerrufener Schlüssel kann nicht wiederhergestellt werden. Stelle daher sicher, dass du weißt, was ihn verwendet, bevor du klickst.
Schlüssel gehören zum Konto, nicht zur Person, die sie erstellt hat. Wenn du einen Teamkollegen von der Seite „Team" entfernst, werden die von ihm erstellten Schlüssel nicht widerrufen. Integriere eine Schlüsselüberprüfung in deine Offboarding-Prozesse: Entferne die Person, komme dann hierher und widerrufe alles, das sie erstellt hat.
Schlüsselerstellung und Widerruf werden beide im Audit-Log unter den Aktionen api_key.* mit Akteur und ursprünglicher IP-Adresse protokolliert.
Der Remote-Build-Cache
Die Seite Entwickler, in der Gruppe „Advanced" der Einstellungsleiste, bietet einen Remote-Build-Cache. Das Panel beschreibt ihn als eine Möglichkeit, „Turborepo- und Nx-Builds zu beschleunigen, indem ein verteilter Cache auf Computern und CI-Pipelines geteilt wird".
- Gehe zu Einstellungen, dann Entwickler.
- Klicke auf Remote-Cache aktivieren.
- Kopiere das Token aus dem Panel mit der Überschrift "New token generated. Copy it now, it won't be shown again".
Stelle dann zwei Umgebungsvariablen in deiner CI-Konfiguration oder lokaler .env.local ein:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
Die Team-ID ist deine KapsuleHost-Konto-ID, die in den Setupanweisungen auf der gleichen Seite angezeigt wird.
Die Seite gibt ihre eigene Kompatibilität an: Turborepo 1.x und später, Nx 16 und später, und jedes Tool, das das gleiche Remote-Cache-Protokoll implementiert. Artefakte werden pro Konto gespeichert und werden niemals über Konten hinweg geteilt.
Zwei weitere Steuerelemente befinden sich auf der Karte:
- Token rotieren gibt ein neues Token aus und macht das alte ungültig. Alle CI-Jobs, die noch das alte Token haben, stoppen die Cache-Nutzung. Rotiere und aktualisiere deine Secrets zusammen.
- Deaktivieren schaltet den Cache ganz aus.
Wahl zwischen den beiden
Sie lösen nicht verwandte Probleme und sind nicht austauschbar.
Verwende einen API-Schlüssel, wenn etwas außerhalb von KapsuleHost den Zustand deines Kontos kennen muss: ein Status-Board, das deine Seiten auflistet, ein Skript, das dich vor ablaufenden Domains warnt, ein Bestandsexport.
Verwende den Remote-Build-Cache, wenn deine Builds langsam sind, weil jeder Computer und jede CI-Ausführung die gleichen unveränderten Pakete neu erstellt. Das hat nichts mit deinen gehosteten Seiten zu tun und liest deine Kontodaten nicht.
Fehlerbehebung
Jede Anfrage gibt 401 zurück. Bestätige, dass du den Header als Authorization: Bearer <key> mit einem einzelnen Leerzeichen gesendet hast, dass der Schlüssel beim Kopieren nicht gekürzt wurde, und dass er nicht widerrufen wurde. Vergleiche den Anfang deines Schlüssels mit der Spalte Präfix, um sicherzustellen, dass du den Schlüssel verwendest, von dem du denkst, dass er es ist.
Eine Anfrage gibt 403 mit Angabe eines Scope zurück. Der Schlüssel trägt diesen Scope nicht. Scopes werden bei der Schlüsselerstellung festgelegt. Erstelle daher einen Ersatz mit den richtigen Scopes und widerrufe den alten.
Ich kann die Karte „API-Schlüssel" nicht sehen. Sie befindet sich auf der Seite „Sicherheit", nicht auf der Seite „Entwickler". Die Seite „Entwickler" enthält nur den Build-Cache.
Die Schaltfläche „Neuer Schlüssel" macht nichts. Deine Rolle liegt unter „Admin". Bitte den Owner oder einen Admin.
Builds treffen den Cache nicht. Überprüfe, dass beide TURBO_TOKEN und TURBO_TEAM in der Build-Umgebung vorhanden sind, dass das Token seit seiner Einstellung nicht rotiert wurde, und dass die Seite immer noch das Badge Aktiv anzeigt.
Ein Schlüssel, den ich nicht erstellt habe, ist erschienen. Behandle ihn als einen Sicherheitsverstoß. Widerrufe ihn, dann arbeite dich durch Account-Sicherheit durch und überprüfe das Audit-Log auf weitere Änderungen.