Konto
API-Schlüssel und Entwicklerzugriff
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…
API Keys und Developer Access
Kapsule bietet dir zwei Developer-Oberflächen: begrenzte API-Schlüssel zum programmgesteuerten Lesen deines Kontos und einen Remote-Build-Cache, der Turborepo- und Nx-Builds auf deinen eigenen Maschinen und CI-Läufern beschleunigt.
Keines ist standardmäßig aktiviert. Beide werden aus Settings erstellt, und beide geben dir ein Geheimnis genau einmal.
Erstellen eines API-Schlüssels
API-Schlüssel befinden sich unter Settings, dann Security, in der API Keys-Karte.
- Gehe zu Settings, dann Security.
- Scrolle zu API Keys und klicke auf New key.
- 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, also notiere dir, wo der Schlüssel verwendet wird.
- Klicke auf die Scope-Chips, um auszuwählen, was der Schlüssel darf. Drei Read-Scopes sind vorausgewählt:
read:sites,read:emailundread:domains. Klicke auf einen Chip, um ihn hinzuzufügen oder zu entfernen. - Klicke auf Create.
Der vollständige Schlüssel wird einmal angezeigt, in einem grünen Panel mit der Überschrift „Copy now". Kopiere ihn sofort in deinen Secret Store. 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 anzeigen kann.
Der Schlüssel wird kein zweites Mal 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, daher lohnt es sich, eine unerwartete E-Mail sofort zu untersuchen.
Die Scopes
Sieben Scopes werden angeboten:
| Scope | Gewährt |
|---|---|
read:sites | Lesen deiner Websites |
write:sites | Reserviert für Schreibvorgänge auf Websites |
read:email | Lesen deiner Mailboxen |
write:email | Reserviert für Schreibvorgänge auf Mailboxen |
read:domains | Lesen deiner Domains |
write:domains | Reserviert für Schreibvorgänge auf Domains |
read:billing | Reserviert zum Lesen von Abrechnungsdaten |
Die Customer-API ist heute schreibgeschützt. Die write:-Scopes und read:billing können bei einem Schlüssel ausgewählt werden, aber kein Customer-Endpoint nutzt sie derzeit, daher hat die Gewährung keine Auswirkungen. Gewähre nur die Read-Scopes, die du wirklich brauchst, und überprüfe den Schlüssel erneut, wenn Write-Endpoints verfügbar sind.
Verwenden eines Schlüssels
Sende den Schlüssel als Bearer-Token im Authorization-Header.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Drei Endpoints akzeptieren einen Customer-API-Schlüssel:
| Endpoint | Erforderlicher Scope | Gibt zurück |
|---|---|---|
GET /api/v1/sites | read:sites | Deine Websites mit Domain, Anwendungstyp und Status |
GET /api/v1/domains | read:domains | Deine Domains mit Status und Ablaufdatum |
GET /api/v1/mailboxes | read:email | Deine Mailboxen |
Eine Anfrage ohne Schlüssel, mit einem unbekannten Schlüssel oder 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 benötigten Scope nennt. Jeder erfolgreiche Aufruf aktualisiert den Zeitstempel der letzten Verwendung des Schlüssels.
Abfrage sanft durchführen. Diese Endpoints lesen Live-Kontodaten, und eine enge Schleife gegen sie 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.
Überprüfen und Widerrufen von Schlüsseln
Die API Keys-Tabelle listet jeden aktiven Schlüssel nach Name, Prefix (der sichtbare Anfang des Schlüssels) und Scopes auf. Klicke auf Revoke am Ende einer Zeile, um ihn zu deaktivieren.
Das Widerrufen tritt sofort in Kraft 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, daher stelle sicher, dass du weißt, wer ihn verwendet, bevor du klickst.
Schlüssel gehören zum Konto, nicht zur Person, die sie erstellt hat. Das Entfernen eines Teamkollegen von der Team-Seite widerruft keine Schlüssel, die sie erstellt haben. Integriere eine Schlüsselüberprüfung in dein Offboarding: entferne die Person und komme dann hier her, um alle von ihr erstellten Schlüssel zu widerrufen.
Schlüsselerstellung und Widerruf werden beide im Audit-Log unter den api_key.*-Aktionen mit dem Akteur und der ursprünglichen IP-Adresse aufgezeichnet.
Der Remote Build Cache
Die Developer-Seite, in der Advanced-Gruppe der Einstellungsleiste, bietet einen Remote Build Cache. Das Panel beschreibt ihn als eine Möglichkeit, „Turborepo- und Nx-Builds durch Sharing eines verteilten Cache über Maschinen und CI-Pipelines zu beschleunigen."
- Gehe zu Settings, dann Developer.
- Klicke auf Enable remote cache.
- Kopiere das Token aus dem Panel mit der Überschrift „New token generated. Copy it now, it won't be shown again".
Setze dann zwei Umgebungsvariablen in deiner CI-Konfiguration oder deinem lokalen .env.local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
Die Team-ID ist deine Kapsule-Konto-ID, die in den Setupanweisungen auf derselben 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 nie über Konten hinweg freigegeben.
Zwei weitere Steuerelemente befinden sich auf der Karte:
- Rotate token gibt ein neues Token aus und macht das alte ungültig. Alle CI-Jobs, die das alte Token noch halten, stoppen die Verwendung des Cache, daher rotieren und aktualisiere deine Secrets zusammen.
- Disable schaltet den Cache ganz aus.
Wählen zwischen den beiden
Sie lösen unverwandte Probleme und sind nicht austauschbar.
Verwende einen API-Schlüssel, wenn etwas außerhalb von Kapsule den Status deines Kontos kennen muss: ein Status-Board, das deine Websites auflistet, ein Skript, das dich vor ablaufenden Domains warnt, ein Inventar-Export.
Verwende den Remote Build Cache, wenn deine Builds langsam sind, weil jede Maschine und jeder CI-Lauf die gleichen unveränderten Pakete neu erstellt. Er hat nichts mit deinen gehosteten Websites zu tun und liest deine Kontodaten nicht.
Wenn du von Git aus bereitstellen möchtest, anstatt eine API aufzurufen, schaue dir stattdessen Kapsule Orbit an. Es erstellt und versendet direkt aus deinem Repository, mit Build-Caching, das für dich erledigt wird.
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 Prefix-Spalte, um sicherzustellen, dass du den Schlüssel verwendest, den du verwenden möchtest.
Eine Anfrage gibt 403 zurück und nennt einen Scope. Der Schlüssel hat diesen Scope nicht. Scopes sind festgelegt, wenn der Schlüssel erstellt wird, daher erstelle einen Ersatz mit den richtigen Scopes und widerrufe den alten.
Ich kann die API Keys-Karte nicht sehen. Sie befindet sich auf der Security-Seite, nicht auf der Developer-Seite. Die Developer-Seite enthält nur den Build Cache.
Die New key-Schaltfläche tut nichts. Deine Rolle ist niedriger als Admin. Biete den Owner oder einen Admin um Hilfe.
Builds treffen den Cache nicht. Überprüfe, dass beide TURBO_TOKEN und TURBO_TEAM in der Build-Umgebung vorhanden sind, dass das Token nicht rotiert wurde, seit du es gesetzt hast, und dass die Seite immer noch das Active-Badge anzeigt.
Ein Schlüssel, den ich nicht erstellt habe, ist erschienen. Behandle ihn als Kompromittierung. Widerrufe ihn, arbeite dann durch Account Security und überprüfe das Audit-Log auf weitere Änderungen.