# API-Schlüssel und Entwicklerzugriff

Source: https://support.kapsulehost.com/de-de/developer-api-access

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**.

![Karte „API-Schlüssel" in den KPanel-Sicherheitseinstellungen mit sichtbaren Scope-Chips](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. Gehe zu **Einstellungen**, dann **Sicherheit**.
2. Scrolle zu **API-Schlüssel** und klicke auf **Neuer Schlüssel**.
3. 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.
4. Klicke auf die Scope-Chips, um auszuwählen, was der Schlüssel tun darf. Drei Lesescopes sind vorausgewählt: `read:sites`, `read:email` und `read:domains`. Klicke auf einen Chip, um ihn hinzuzufügen oder zu entfernen.
5. 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.

> **Warning:** 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 |

> **Note:** 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`.

```sh
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.

> **Tip:** 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.

> **Important:** 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"](https://support.kapsulehost.com/de-de/account-team-members) 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](https://support.kapsulehost.com/de-de/account-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".

1. Gehe zu **Einstellungen**, dann **Entwickler**.
2. Klicke auf **Remote-Cache aktivieren**.
3. 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:

```sh
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](https://support.kapsulehost.com/de-de/account-security) durch und überprüfe [das Audit-Log](https://support.kapsulehost.com/de-de/account-audit-log) auf weitere Änderungen.