Rollen beheren¶

Een rol bepaalt wat iemand mag. Deze pagina laat zien hoe je een lid of een groep een rol geeft en weer afneemt, hoe je een rol laat gelden in de organisaties onder de jouwe, en hoe je eigen rollen maakt. Wat rollen zijn en welke ingebouwde rollen er zijn, staat in Rollen en toegang.

Rollen geven kan met people-admin (alleen member en people-admin) of org-admin; eigen rollen maken, wijzigen en verwijderen kan alleen org-admin. Rollen hebben nog geen scherm in OS: je beheert ze via de API. De voorbeelden gebruiken $OS, $TOKEN en $ORG zoals in Groepen beheren.

De rollen bekijken¶

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

OS toont eerst de ingebouwde rollen, met hun naam als id (org-admin), daarna de eigen rollen, met een id als rol_.... Elke rol toont zijn rules, dus je leest precies wat een ingebouwde rol mag met GET .../roles/org-admin.

Een rol geven¶

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 antwoordt 201 met de toekenning:

{"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 is de naam van een ingebouwde rol of het id van een eigen rol.
• Geef member_id voor één lid, of group_id voor een groep; dan heeft elk lid van de groep de rol.
• reach is organisation (standaard) of descendants, zie hieronder.

Je kunt alleen een rol geven die je zelf hebt, met minstens hetzelfde bereik, of waarvan je elke regel hebt (waarom). Een lid heeft hoogstens 32 rollen, member meegeteld.

GET .../role-assignments?member_id=mem_... of ?group_id=grp_... toont de rollen van één lid of groep.

Een rol afnemen¶

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

Je neemt een rol af als je regels je toestaan die rol te geven (use op de rol) en je het lid of de groep mag wijzigen; of je de rol zelf hebt, doet hier niet toe. Een organisatie houdt altijd minstens één actief lid dat org-admin zelf heeft, niet via een groep. Een afname die er geen overlaat, weigert OS met 409; geef eerst een ander lid org-admin.

Een rol laten gelden in de organisaties eronder¶

Met "reach": "descendants" geldt de rol ook in elke organisatie onder de jouwe. Zo geeft een partner zijn supportmedewerkers toegang tot de organisaties van zijn klanten, zonder dat ze daar lid worden. Je kunt dit bereik alleen geven als je de rol zelf met bereik descendants hebt. OS weigert met 409 als een organisatie eronder daardoor meer regels in de AI-functies zou krijgen dan ze mag (500), of meer dan 32 eigenschappen en 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"}'

Een eigen rol maken¶

Een eigen rol is een naam met regels. Deze rol laat een teamleider de leden van zijn eigen afdeling zien en beheren:

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

De regel zegt: een lid mag een ander lid zien en wijzigen als een afdeling van dat lid ook een afdeling van hemzelf is. Hoe je regels schrijft, staat in Soorten en acties.

• name is uniek in de organisatie en geen naam van een ingebouwde rol, hoogstens 64 tekens.
• rules: hoogstens 200, elk met hoogstens 15 voorwaarden.
• labels zijn optioneel, zoals bij een groep. Het label builtin is van de ingebouwde rollen.
• Een organisatie heeft hoogstens 100 eigen rollen.

Regels over memory_write, share_link, artifact_download, router en egress_host kan een rol niet bevatten (422): die gelden voor de hele organisatie en staan in het regeldocument. Een voorwaarde noemt role, group, of een eigenschap die je organisatie of een organisatie erboven heeft vastgelegd.

Je moet elke regel die de rol toestaat zelf hebben. Een weigerende regel over beheer (organisaties, leden, uitnodigingen, groepen, rollen, regels en eigenschappen) kan niet; op de AI-functies wel.

Een eigen rol wijzigen of verwijderen¶

Je vervangt een eigen rol in zijn geheel met PUT .../roles/rol_... en noemt de versie die je las in If-Match, zoals bij een groep. Alleen de regels die je toevoegt, worden gecontroleerd tegen wat je zelf hebt: je kunt een rol bewerken die een regel bevat die een ander heeft toegevoegd. Wie de rol heeft, valt meteen onder de nieuwe regels.

DELETE .../roles/rol_... verwijdert de rol en neemt hem af van iedereen die hem had. Ingebouwde rollen wijzig en verwijder je niet.

Als OS weigert¶