Service Accounts & API-Keys¶

Ein Service Account ist ein Konto für eine Maschine statt für einen Menschen — Home Assistant, Grafana, eine CI/CD-Pipeline. Er gehört zu genau einem Garten (Mandanten), meldet sich nie mit Passwort an und arbeitet ausschließlich mit API-Keys. So muss keine Integration mit deinem persönlichen Key laufen, und du kannst ihr den Zugang jederzeit entziehen, ohne deinen eigenen anzufassen.

Was einen Service Account ausmacht¶

• Kein Passwort, keine Anmeldung, keine Sitzung. Ein Login mit seiner Adresse wird abgewiesen.
• Genau ein Garten. Er wird als Mitglied mit der Rolle Beobachter (viewer) oder Gärtner (grower) angelegt — nie als Leitung, ohne Verwaltungsrechte. Auch über die Mitgliederverwaltung wird er nicht zur Leitung (403).
• Seine API-Keys gelten nur in diesem Garten. Jeder Key ist an den Garten gebunden: Ein Aufruf in einem anderen Garten antwortet 403, ebenso jede kontobezogene Route.
• Er gründet keinen Garten und nimmt keine Einladung an (403).
• Er belegt einen Platz im Mitgliederlimit des Gartens.
• Seine Adresse ist zufällig und unzustellbar (sa-…@service.example.com); er bekommt keine E-Mails.

Voraussetzungen¶

• Du bist im Garten Leitung (lead) und hast den technischen Verwaltungsbereich (technical). Beides wird aus deiner gespeicherten Mitgliedschaft gelesen.
• Du bestätigst jede Änderung mit deinem eigenen Passwort (Step-up). Ohne lokales Passwort holst du dir einen Code oder meldest dich frisch an — Aktion service_account_change, Ziel: der Schlüssel des Gartens beim Anlegen, <garten-schlüssel>|<service-account-schlüssel> beim Rotieren und Entfernen.
• Eine Anfrage, die selbst mit einem API-Key authentifiziert ist, darf nichts davon (403).
• Im Light-Modus gibt es keine Service Accounts (403).

Service Account anlegen¶

curl -X POST "https://kamerplanter.example.com/api/v1/t/mein-garten/service-accounts" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home Assistant",
    "role": "grower",
    "ip_allowlist": ["192.168.1.0/24"],
    "rate_limit_per_minute": 600,
    "expires_at": "2027-04-01T00:00:00+02:00",
    "current_password": "<dein aktuelles Passwort>"
  }'

Antwort (201 Created):

{
  "key": "8f3c…",
  "display_name": "Home Assistant",
  "role": "grower",
  "membership_key": "51a0…",
  "api_key": {
    "key": "a7d2…",
    "label": "Home Assistant",
    "raw_key": "kp_…",
    "key_prefix": "kp_Xy1aB",
    "tenant_scope": "<schlüssel von mein-garten>",
    "created_at": "2026-10-05T10:00:00Z",
    "ip_allowlist": ["192.168.1.0/24"],
    "rate_limit_per_minute": 600,
    "expires_at": "2027-03-31T22:00:00Z"
  }
}

Ablehnungen, bevor nach deinem Passwort gefragt wird:

Danach: 401 ohne oder mit falschem Passwort, 429 STEP_UP_LOCKED nach zu vielen Fehlversuchen.

Die Einschränkungen eines API-Keys¶

Dieselben drei Felder nimmt auch POST /api/v1/auth/api-keys an, mit dem du einen Key für dein eigenes Konto ausstellst. Sie gelten auf der REST-API und auf dem MCP-Server gleich.

GET /api/v1/auth/api-keys zeigt die drei Werte für deine eigenen Keys an.

Service Accounts auflisten¶

curl "https://kamerplanter.example.com/api/v1/t/mein-garten/service-accounts" \
  -H "Authorization: Bearer {access_token}"

Die Liste nennt jeden aktiven Service Account mit Rolle und seinen Keys in diesem Garten — nur Metadaten (Präfix, Einschränkungen, letzter Zugriff, widerrufen ja/nein), nie den Key selbst.

Key rotieren¶

curl -X POST "https://kamerplanter.example.com/api/v1/t/mein-garten/service-accounts/{sa_key}/rotate-key" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"overlap_minutes": 30, "current_password": "<dein aktuelles Passwort>"}'

• Der neue Key übernimmt IP-Allowlist und Ratenlimit des jüngsten bisherigen Keys. Ein neues Ablaufdatum gibst du optional mit expires_at an.
• overlap_minutes (0–1440, Standard 0): Bei 0 sind die bisherigen Keys sofort widerrufen — der richtige Wert, wenn ein Key in falsche Hände geraten ist. Bei einem Wert über 0 funktionieren sie noch so viele Minuten weiter, damit du die Integration ohne Unterbrechung umstellen kannst; danach lehnt jeder Aufruf sie ab.
• Die Antwort enthält den neuen Key (api_key.raw_key, nur dieses eine Mal), previous_keys_end_at (das Ende des Übergangsfensters oder null) und replaced_key_count.

Service Account entfernen¶

curl -X DELETE "https://kamerplanter.example.com/api/v1/t/mein-garten/service-accounts/{sa_key}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"current_password": "<dein aktuelles Passwort>"}'

Alle Keys des Service Accounts in diesem Garten werden sofort widerrufen, seine Mitgliedschaft endet (ihm zugewiesene Aufgaben verlieren die Zuweisung), und das Konto wird deaktiviert. Was er geschrieben hat, behält ihn als Urheber.

Anlegen, Rotieren und Entfernen stehen im Sicherheitsprotokoll, das Plattform-Admins lesen können.

Den Key verwenden¶

curl "https://kamerplanter.example.com/api/v1/t/mein-garten/sites" \
  -H "Authorization: Bearer kp_…"

Der Key handelt mit der Rolle des Service Accounts im Garten — ein viewer liest nur, ein grower darf auch schreiben, aber nichts löschen.

Was noch fehlt¶

Häufige Fragen¶

Siehe auch¶

• Authentifizierung
• Fehlerbehandlung
• Umgebungsvariablen
• MCP-Server