Groepen beheren¶

Met een groep geef je een heel team in één keer dezelfde rollen en eigenschappen. Deze pagina laat zien hoe je een groep maakt, leden toevoegt en verwijdert en een groep weer opheft. Wat een groep is, staat in Rollen en toegang.

Groepen beheer je met de rol people-admin of org-admin; een groep verwijderen kan alleen org-admin. Groepen hebben nog geen scherm in OS: je beheert ze via de API.

Voor je begint¶

De voorbeelden gebruiken drie variabelen in je shell:

OS=https://os.example.com      # het adres van OS
TOKEN=...                      # een toegangstoken van je eigen aanmelding
ORG=org_...                    # het id van je organisatie

Hoe een verzoek aan OS werkt, en wat elk antwoord bevat, staat in De toegangs-API.

Een groep maken¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/groups" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"name": "Verkoop", "labels": {"department": "sales"}}'

OS antwoordt 201 met de groep:

{"id": "grp_...", "name": "Verkoop", "labels": {"department": ["sales"]},
 "version": 1, "allowed_actions": ["see", "write", "delete"]}

• name is uniek in de organisatie, hoogstens 200 tekens.
• labels zijn optioneel: labels die regels over groepen kunnen lezen, hoogstens 32. Een label heeft één waarde of een lijst waarden.

GET /api/v1/organisations/$ORG/groups toont de groepen die je mag zien, per pagina van hoogstens 200 (limit, standaard 50); geef next_cursor mee als cursor voor de volgende pagina.

Een groep hernoemen of anders labelen¶

Je vervangt de groep in zijn geheel en noemt de versie die je las. Die staat in version en in de kop ETag van het antwoord.

curl -s -X PUT "$OS/api/v1/organisations/$ORG/groups/grp_..." \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -H 'If-Match: "1"' \
    -d '{"name": "Verkoop Benelux", "labels": {"department": "sales"}}'

Heeft iemand de groep intussen gewijzigd, dan antwoordt OS 409. Lees de groep opnieuw en herhaal je wijziging.

Leden toevoegen en verwijderen¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/groups/grp_.../members" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"membership_id": "mem_..."}'

Het lid krijgt meteen alle rollen en waarden van de groep. Daarom moet je zelf elke rol en elke waarde hebben die de groep geeft; anders weigert OS met 403 en noemt het wat je mist (waarom).

• GET .../groups/grp_.../members toont de leden die je mag zien.
• DELETE .../groups/grp_.../members/mem_... haalt een lid uit de groep. Het lid verliest wat de groep gaf, en houdt wat het zelf of via andere groepen heeft.

Een lid zit in hoogstens 32 groepen.

Een groep rollen of eigenschappen geven¶

Een groep krijgt een rol zoals een lid die krijgt, met group_id in plaats van member_id: zie Een rol geven en Een waarde geven.

Een groep verwijderen¶

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

OS antwoordt 204. De leden verliezen wat de groep gaf. Rollen en waarden die ze zelf hebben, blijven.

Als OS weigert¶