Gérer les groupes¶

Avec un groupe, vous donnez à toute une équipe, en une seule fois, les mêmes rôles et attributs. Cette page montre comment créer un groupe, ajouter et retirer des membres, et supprimer un groupe. Ce qu'est un groupe est expliqué dans Rôles et accès.

Vous gérez les groupes avec le rôle people-admin ou org-admin ; seul org-admin peut supprimer un groupe. Les groupes n'ont pas encore d'écran dans OS : vous les gérez via l'API.

Avant de commencer¶

Les exemples utilisent trois variables dans votre shell :

OS=https://os.example.com      # l'adresse d'OS
TOKEN=...                      # un jeton d'accès issu de votre propre connexion
ORG=org_...                    # l'identifiant de votre organisation

La façon dont une requête à OS fonctionne, et ce que contient chaque réponse, figure dans L'API d'accès.

Créer un groupe¶

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

OS répond 201 avec le groupe :

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

• name est unique dans l'organisation, 200 caractères au maximum.
• labels est facultatif : des étiquettes que les règles sur les groupes peuvent lire, 32 au maximum. Une étiquette a une valeur ou une liste de valeurs.

GET /api/v1/organisations/$ORG/groups affiche les groupes que vous avez le droit de voir, par pages de 200 au maximum (limit, 50 par défaut) ; passez next_cursor comme cursor pour la page suivante.

Renommer un groupe ou changer ses étiquettes¶

Vous remplacez le groupe dans son ensemble et indiquez la version que vous avez lue. Elle figure dans version et dans l'en-tête ETag de la réponse.

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": "Ventes Benelux", "labels": {"department": "sales"}}'

Si quelqu'un a modifié le groupe entre-temps, OS répond 409. Relisez le groupe et recommencez votre modification.

Ajouter et retirer des membres¶

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_..."}'

Le membre reçoit aussitôt tous les rôles et valeurs du groupe. Vous devez donc avoir vous-même chaque rôle et chaque valeur que le groupe donne ; sinon OS refuse avec 403 et indique ce qui vous manque (pourquoi).

• GET .../groups/grp_.../members affiche les membres que vous avez le droit de voir.
• DELETE .../groups/grp_.../members/mem_... retire un membre du groupe. Le membre perd ce que le groupe donnait, et garde ce qu'il a lui-même ou par d'autres groupes.

Un membre fait partie de 32 groupes au maximum.

Donner des rôles ou des attributs à un groupe¶

Un groupe reçoit un rôle comme un membre le reçoit, avec group_id au lieu de member_id : voir Donner un rôle et Donner une valeur.

Supprimer un groupe¶

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

OS répond 204. Les membres perdent ce que le groupe donnait. Les rôles et valeurs qu'ils ont eux-mêmes restent.

Quand OS refuse¶