Dienstkonten¶

Ein Dienstkonto ist ein Mitglied Ihrer Organisation, das keine Person ist, sondern ein Programm: eine Anbindung, ein Skript, das nachts läuft, ein anderes System, das OS aufruft. Alles, was eine Person in OS kann, kann ein Dienstkonto über die API, auf genau dieselbe Weise entschieden. Diese Seite richtet sich an Administratoren: wer die Administratorrolle der Organisation hat.

Ein Schlüssel kann genau das, was sein Dienstkonto darf, und nicht mehr. Wer einen Schlüssel hat, handelt als das Dienstkonto. Geben Sie einem Dienstkonto wenige Rechte, geben auch seine Schlüssel wenige Rechte. Geben Sie einem Dienstkonto also nur, was das Programm wirklich braucht.

Auf dem Bildschirm¶

Öffnen Sie Benutzerverwaltung, wählen Sie Service-Konten und gehen Sie durch:

Die Liste. Sie sehen Ihre Dienstkonten. Wählen Sie Erstellen Sie ein neues Service-Konto, um eines anzulegen.
Anlegen. Füllen Sie Name und, wenn Sie möchten, Beschreibung aus, wählen Sie die Rollen, Gruppen und Attributwerte, die es bekommt (Sie können nur vergeben, was Sie selbst haben), und wählen Sie Service-Konto erstellen.
Schlüssel. Öffnen Sie das Dienstkonto und wählen Sie den Tab Schlüssel. Wählen Sie Erstellen Sie einen neuen API-Schlüssel, füllen Sie API-Schlüssel-Name und Ablaufdatum aus und wählen Sie API-Schlüssel erstellen. Der Bildschirm zeigt das Geheimnis einmal, mit der Client-ID und der Adresse für das Token: bewahren Sie es sofort auf. Bei jedem Schlüssel sehen Sie den Status, wann er abläuft, wann er zuletzt benutzt wurde und die Warnungen. Läuft ein Schlüssel innerhalb von 14 Tagen ab, erhalten auch die Administratoren der Organisation eine Benachrichtigung in OS und per E-Mail, einmal pro Ablaufdatum. Die alte Kopie eines rotierten Schlüssels warnt nicht.
Rotieren. Wählen Sie bei einem aktiven Schlüssel Rotieren, geben Sie das neue Ablaufdatum und die Überlappung in Stunden ein und bestätigen Sie. Der Bildschirm zeigt das neue Geheimnis einmal. Nur wer alles hat, was das Dienstkonto hat, bekommt diese Schaltfläche.
Widerrufen. Wählen Sie bei einem Schlüssel den Papierkorb und bestätigen Sie. Der Schlüssel funktioniert dann nicht mehr.
Rechte. Der Tab Rechte zeigt die Rollen, Gruppen und Attributwerte des Dienstkontos. Wählen Sie Rechte hinzufügen, um Rechte zu vergeben, oder nehmen Sie eines zurück; Sie können nur vergeben und zurücknehmen, was Sie selbst dürfen.
Zugriff. Der Tab Zugriff zeigt je Art von Objekt, was das Dienstkonto darf (Ansehen, Verwenden, Ändern, Löschen), und damit auch, was kann, wer seinen Schlüssel hat. Schauen Sie hier nach, bevor Sie einen Schlüssel anlegen.
Deaktivieren und löschen. Oben auf der Seite wählen Sie Deaktivieren (oder Aktivieren) oder Löschen.

Ein Dienstkonto anlegen¶

Wählen Sie einen Namen (eindeutig in Ihrer Organisation) und, wenn Sie möchten, eine Beschreibung, wofür es ist.
Wählen Sie die Rollen, Gruppen und Attributwerte, die es bekommt, wie bei einer Einladung. Sie können nur vergeben, was Sie selbst haben (warum).
Das Dienstkonto ist sofort aktiv. Es gibt niemanden, der eine Einladung annimmt.

Ein Dienstkonto steht in derselben Mitgliederliste wie die Menschen, mit denselben Rollen, Gruppen und Attributen. Nur wer Dienstkonten verwaltet, ändert sie, auf dieselbe Weise wie bei einer Person; ein Personenverwalter sieht ein Dienstkonto in der Liste, ändert daran aber nichts. Ein Dienstkonto zählt nicht als letzter Administrator: Eine Organisation behält immer eine Person mit der Administratorrolle.

Was ein Dienstkonto nicht kann¶

Was eine Person nur für sich selbst tut, kann ein Dienstkonto nicht: Einstellungen festlegen, sich selbst löschen lassen und eine Einladung annehmen. OS lehnt das mit 403 ab. Ein Dienstkonto wird von einem Administrator verwaltet und gelöscht.

Schlüssel¶

Ein Programm meldet sich mit einem Schlüssel an. Ein Dienstkonto kann mehrere Schlüssel haben (standardmäßig höchstens fünf gleichzeitig), jeden mit eigenem Namen.

Legen Sie einen Schlüssel mit einem Namen und einem Ablaufdatum an. Es ist Pflicht und liegt höchstens ein Jahr in der Zukunft.
OS zeigt das Geheimnis des Schlüssels einmal, mit der Client-ID und der Adresse, bei der das Programm ein Token anfordert. Bewahren Sie das Geheimnis sofort an einem sicheren Ort auf; OS zeigt es nie wieder.
Nach einigen Sekunden funktioniert der Schlüssel.

Nur wer alles hat, was das Dienstkonto hat, darf einen Schlüssel dafür anlegen. So kann niemand über einen Schlüssel mehr Rechte erlangen, als er schon hat.

Das Programm fordert mit der Client-ID und dem Geheimnis ein Token an und sendet dieses Token an OS:

curl -s -X POST "$TOKEN_ENDPOINT" \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET"

Ein Token ist fünf Minuten gültig; das Programm fordert danach ein neues an.

Ersetzen ohne Unterbrechung¶

Rotieren Sie einen Schlüssel: OS legt einen neuen Schlüssel mit einem neuen Geheimnis an, und der alte funktioniert noch eine Überlappung lang (standardmäßig 24 Stunden, höchstens 30 Tage). Tragen Sie das neue Geheimnis im Programm ein, bevor die Überlappung vorbei ist.

Zurückziehen, Ablauf und Warnungen¶

Ein zurückgezogener Schlüssel funktioniert ab der nächsten Anfrage nicht mehr.
Ein abgelaufener Schlüssel funktioniert ab seinem Ablaufdatum nicht mehr.
Bei jedem Schlüssel sehen Sie, wann OS ihn zuletzt benutzt sah (auf fünf Minuten genau). OS warnt bei einem Schlüssel, der innerhalb von 14 Tagen abläuft, der 30 Tage nicht benutzt wurde oder der eine Woche nach dem Anlegen noch nie benutzt wurde.

Über MCP verwenden¶

Ein eigener Agent, der MCP spricht, kann als das Dienstkonto mit OS arbeiten, mit den Rechten des Kontos: Jede Operation der API von OS ist dann ein Tool. Öffnen Sie das Dienstkonto; auf dem Reiter Allgemein steht unter Über MCP verwenden:

die MCP-Adresse, an die der Agent seine Aufrufe schickt;
die Token-Adresse, bei der der Agent ein Token holt;
Token abrufen und Tools abfragen: zwei Beispiele zum Kopieren.

Verwenden Sie die Client-ID eines Schlüssels aus dem Reiter Schlüssel und das Geheimnis dieses Schlüssels. Setzen Sie das Geheimnis anstelle von YOUR_CLIENT_SECRET ein und das Token aus dem ersten Schritt anstelle von ACCESS_TOKEN:

curl -s -X POST '<Token-Adresse>' \
  -d grant_type=client_credentials \
  -d client_id='<Client-ID>' \
  -d client_secret='YOUR_CLIENT_SECRET'

curl -s -X POST '<MCP-Adresse>' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Ein Token gilt fünf Minuten; holen Sie dann ein neues. Hat das Dienstkonto keinen aktiven Schlüssel, sagt die Karte, dass Sie zuerst einen anlegen. Stehen KI-Apps in der Organisation auf Aus, bekommt der Agent jeden Aufruf abgelehnt, bis ein Administrator es einschaltet (Arbeiten aus KI-Apps); die Karte sagt das dann ebenfalls.

Was ein Dienstkonto darf und was es tat¶

Bei jedem Dienstkonto sehen Sie pro Art von Bestandteil, was es darf. Im Prüfprotokoll sehen Sie, was es tat und was mit dem Dienstkonto und seinen Schlüsseln getan wurde. Geheimnisse stehen nie im Prüfprotokoll.

Deaktivieren und löschen¶

Deaktivieren: Ab der nächsten Anfrage lehnt OS dem Dienstkonto alles in der Organisation ab, unter jedem Schlüssel; nur GET /api/v1/me antwortet noch, ohne Mitgliedschaft. Wieder aktivieren macht dieselben Schlüssel wieder nutzbar.
Löschen: endgültig. Alle Schlüssel werden zurückgezogen. Was das Dienstkonto in den KI-Funktionen erstellt hat, bleibt bei der Organisation, es sei denn, Sie wählen das Löschen.

Wenn OS ablehnt¶

401: der Schlüssel ist zurückgezogen oder abgelaufen, oder das Token stammt von einem anderen Client.
403: Sie vergeben eine Rolle, Gruppe oder einen Wert, den Sie selbst nicht haben, oder Sie legen einen Schlüssel für ein Dienstkonto an, das mehr hat als Sie; die Meldung nennt, was.
409: der Name ist schon vergeben, das Dienstkonto hat schon die höchste Anzahl Schlüssel, oder das Dienstkonto wurde inzwischen geändert.
422: ein Ablaufdatum, das fehlt, vorbei ist oder zu weit in der Zukunft liegt.

Über die API¶

POST /api/v1/organisations/{id}/service-accounts mit name und nach Wahl description, roles, groups und attributes, wie bei einer Einladung.
GET, PATCH (mit If-Match) und DELETE /api/v1/organisations/{id}/service-accounts/{account_id}.
POST /api/v1/organisations/{id}/service-accounts/{account_id}/keys mit label und expires_at; die Antwort enthält client_id, client_secret und token_endpoint.
POST …/keys/{key_id}/rotate mit expires_at und overlap_hours; DELETE …/keys/{key_id} zieht einen Schlüssel zurück.
GET /api/v1/organisations/{id}/memberships/{account_id}/access zeigt, was es darf; GET /api/v1/organisations/{id}/audit-events?actor={account_id}, was es tat.