# API-Schlüssel

Source : https://webgune.cloud/de-de/docs/cles-api · Mis à jour le 2026-10-27

# API-Schlüssel

API-Schlüssel (Präfix `wgk_`) gewähren programmatischen Zugriff auf Ihr Konto: [CLI](/docs/cli), [VS Code-Erweiterung](/docs/extension-vscode), CI-Skripte, oder direkte Aufrufe der [API](/docs/reference-api).

## Einen Schlüssel erstellen

**Dashboard → Entwickler → API-Schlüssel → Neuer Schlüssel**:

| Einstellung | Rolle |
|---------|------|
| **Name** | Zur Wiedererkennung („CI Produktion", „privater Laptop"…) |
| **Scopes** | Was der Schlüssel tun darf (siehe unten) |
| **Ratenlimit** | Erlaubte Anfragen/Minute (60 standardmäßig) |
| **Ablauf** | Optional, empfohlen für CI-Schlüssel |

Der vollständige Schlüssel wird **nur einmal** angezeigt, bei der Erstellung. Speichern Sie ihn in einem Secret-Manager; danach bleibt nur seine gekürzte Signatur sichtbar.

## Die Scopes

Ein Scope folgt dem Format `ressource:aktion`:

```
projects:read      # Projekte auflisten und lesen
services:write     # deployen, neu starten, konfigurieren
services:*         # alles zu Diensten
billing:read       # Rechnungen und Abonnement lesen
*                  # alle Rechte (außerhalb von Tests zu vermeiden)
```

**Prinzip des geringsten Privilegs**: ein CI-Schlüssel, der nur deployt, braucht nur `services:write`. Ein Monitoring-Schlüssel, `projects:read`. Erstellen Sie mehrere enge Schlüssel statt eines einzigen breiten.

## Einen Schlüssel verwenden

```bash
curl https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx"
```

Ein Schlüssel agiert **im Namen seines Besitzers**: er erbt Ihre [Rollen auf jedem Projekt](/docs/roles-permissions), niemals mehr. Seine Scopes können nur einschränken, nicht erweitern.

## Für einen Unterkunden agieren (Reseller)

Ein mit aktiviertem **Für Unterkunden agieren** erstellter Schlüssel (vorbehalten dem Eigentümer einer Organisation) kann im Namen eines seiner Unterkunden agieren, indem der Header `X-Act-As-User-Id` hinzugefügt wird:

```bash
curl https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx" \
  -H "X-Act-As-User-Id: usr_des_unterkunden"
```

Der Ziel-Unterkunde muss derselben Organisation angehören, sonst schlägt die Anfrage fehl, als ob die Ressource nicht existierte (404). Die Scopes des Schlüssels gelten weiterhin. Für einen Unterkunden zu agieren gewährt keine Rechte über die des Schlüssels hinaus.

## Audit-Protokoll

Jeder Schlüssel hat sein eigenes Protokoll, einsehbar unter **Dashboard → Entwickler → API-Schlüssel → Protokoll-Symbol**, oder über `GET /api/v1/api-keys/:id/audit-log`: die letzten 100 Aufrufe (Methode, Pfad, Rückgabecode, Dauer, und ob die Anfrage für einen Unterkunden erfolgte). Nützlich, um einen leckenden Schlüssel oder ein still fehlschlagendes Skript zu erkennen.

## Limits

- **WebSockets ausgeschlossen**: Echtzeit-Streams (Live-Logs, Zusammenarbeit) erfordern eine Browser-Session: Ein API-Schlüssel kann sich nicht damit verbinden. Der REST-Snapshot der Logs bleibt zugänglich.
- Ein **abgelaufener oder widerrufener** Schlüssel wird sofort abgelehnt; widerrufen Sie ohne zu zögern jeden potenziell exponierten Schlüssel (der Widerruf ist sofort und wirkt sich nicht auf Ihre anderen Schlüssel aus).
- Jeder Schlüssel hat **sein eigenes** Ratenlimit: Ein außer Kontrolle geratenes Skript erschöpft nicht das Kontingent der anderen.