Rollen verwalten¶

Eine Rolle bestimmt, was jemand darf. Diese Seite zeigt, wie Sie einem Mitglied oder einer Gruppe eine Rolle geben und wieder nehmen, wie Sie eine Rolle in den Organisationen unter Ihrer eigenen gelten lassen und wie Sie eigene Rollen anlegen. Was Rollen sind und welche eingebauten Rollen es gibt, steht unter Rollen und Zugriff.

Rollen vergeben kann people-admin (nur member und people-admin) oder org-admin; eigene Rollen anlegen, ändern und löschen kann nur org-admin. Rollen haben in OS noch keinen Bildschirm: Sie verwalten sie über die API. Die Beispiele nutzen $OS, $TOKEN und $ORG wie unter Gruppen verwalten.

Die Rollen ansehen¶

curl -s "$OS/api/v1/organisations/$ORG/roles" -H "Authorization: Bearer $TOKEN"

OS zeigt zuerst die eingebauten Rollen, mit ihrem Namen als ID (org-admin), dann die eigenen Rollen, mit einer ID wie rol_.... Jede Rolle zeigt ihre rules, Sie lesen also genau, was eine eingebaute Rolle darf, mit GET .../roles/org-admin.

Eine Rolle geben¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/role-assignments" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"role": "people-admin", "member_id": "mem_..."}'

OS antwortet 201 mit der Zuweisung:

{"id": "ras_...", "role": "people-admin", "member_id": "mem_...", "group_id": null,
 "reach": "organisation", "granted_by": "per_...", "created_at": "2026-10-17T09:12:00Z",
 "allowed_actions": ["see", "use", "write", "delete"]}

• role ist der Name einer eingebauten Rolle oder die ID einer eigenen Rolle.
• Geben Sie member_id für ein Mitglied oder group_id für eine Gruppe an; dann hat jedes Mitglied der Gruppe die Rolle.
• reach ist organisation (Standard) oder descendants, siehe unten.

Sie können nur eine Rolle geben, die Sie selbst haben, mit mindestens derselben Reichweite, oder von der Sie jede Regel haben (warum). Ein Mitglied hat höchstens 32 Rollen, member mitgezählt.

GET .../role-assignments?member_id=mem_... oder ?group_id=grp_... zeigt die Rollen eines Mitglieds oder einer Gruppe.

Eine Rolle wieder nehmen¶

curl -s -X DELETE "$OS/api/v1/organisations/$ORG/role-assignments/ras_..." \
    -H "Authorization: Bearer $TOKEN"

Sie nehmen eine Rolle zurück, wenn Ihre Regeln Ihnen erlauben, diese Rolle zu geben (use auf die Rolle) und Sie das Mitglied oder die Gruppe ändern dürfen; ob Sie die Rolle selbst haben, spielt hier keine Rolle. Eine Organisation behält immer mindestens ein aktives Mitglied, das org-admin selbst hat, nicht über eine Gruppe. Eine Rücknahme, die keines übrig ließe, lehnt OS mit 409 ab; geben Sie zuerst einem anderen Mitglied org-admin.

Eine Rolle in den Organisationen darunter gelten lassen¶

Mit "reach": "descendants" gilt die Rolle auch in jeder Organisation unter Ihrer. So gibt ein Partner seinen Supportmitarbeitern Zugriff auf die Organisationen seiner Kunden, ohne dass sie dort Mitglied werden. Diese Reichweite können Sie nur vergeben, wenn Sie die Rolle selbst mit Reichweite descendants haben. OS lehnt mit 409 ab, wenn eine Organisation darunter dadurch mehr Regeln in den KI-Funktionen bekäme, als sie darf (500), oder mehr als 32 Attribute und Labels.

curl -s -X POST "$OS/api/v1/organisations/$ORG/role-assignments" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"role": "org-admin", "group_id": "grp_...", "reach": "descendants"}'

Eine eigene Rolle anlegen¶

Eine eigene Rolle ist ein Name mit Regeln. Diese Rolle lässt eine Teamleiterin oder einen Teamleiter die Mitglieder der eigenen Abteilung sehen und verwalten:

curl -s -X POST "$OS/api/v1/organisations/$ORG/roles" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"name": "Teamleitung", "rules": [
          {"id": "own-department", "effect": "permit", "kind": "membership",
           "actions": ["see", "write"],
           "when": [{"atom": "label_among", "label": "department", "attribute": "department"}]}
        ]}'

Die Regel sagt: Ein Mitglied darf ein anderes Mitglied sehen und ändern, wenn eine Abteilung dieses Mitglieds auch eine Abteilung des eigenen ist. Wie Sie Regeln schreiben, steht unter Arten und Aktionen.

• name ist in der Organisation eindeutig und nicht der Name einer eingebauten Rolle, höchstens 64 Zeichen.
• rules: höchstens 200, jede mit höchstens 15 Bedingungen.
• labels sind optional, wie bei einer Gruppe. Das Label builtin gehört den eingebauten Rollen.
• Eine Organisation hat höchstens 100 eigene Rollen.

Regeln über memory_write, share_link, artifact_download, router und egress_host kann eine Rolle nicht enthalten (422): Sie gelten für die ganze Organisation und stehen im Regeldokument. Eine Bedingung nennt role, group oder ein Attribut, das Ihre Organisation oder eine Organisation darüber festgelegt hat.

Sie müssen jede Regel, die die Rolle erlaubt, selbst haben. Eine verbietende Regel über die Verwaltung (Organisationen, Mitglieder, Einladungen, Gruppen, Rollen, Regeln und Attribute) ist nicht möglich; bei den KI-Funktionen schon.

Eine eigene Rolle ändern oder löschen¶

Sie ersetzen eine eigene Rolle als Ganzes mit PUT .../roles/rol_... und nennen die Version, die Sie gelesen haben, in If-Match, wie bei einer Gruppe. Nur die Regeln, die Sie hinzufügen, werden gegen das geprüft, was Sie selbst haben: Sie können eine Rolle bearbeiten, die eine Regel enthält, die jemand anderes hinzugefügt hat. Wer die Rolle hat, fällt sofort unter die neuen Regeln.

DELETE .../roles/rol_... löscht die Rolle und nimmt sie allen, die sie hatten. Eingebaute Rollen ändern und löschen Sie nicht.

Wenn OS ablehnt¶