Gérer les rôles¶

Un rôle détermine ce qu'une personne peut faire. Cette page montre comment donner un rôle à un membre ou à un groupe et le retirer, comment faire valoir un rôle dans les organisations situées sous la vôtre, et comment créer des rôles propres. Ce que sont les rôles et quels rôles intégrés existent est expliqué dans Rôles et accès.

Donner des rôles est possible avec people-admin (seulement member et people-admin) ou org-admin ; créer, modifier et supprimer des rôles propres n'est possible qu'avec org-admin. Les rôles n'ont pas encore d'écran dans OS : vous les gérez via l'API. Les exemples utilisent $OS, $TOKEN et $ORG comme dans Gérer les groupes.

Voir les rôles¶

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

OS affiche d'abord les rôles intégrés, avec leur nom comme identifiant (org-admin), puis les rôles propres, avec un identifiant comme rol_.... Chaque rôle affiche ses rules : vous lisez donc exactement ce qu'un rôle intégré permet avec GET .../roles/org-admin.

Donner un rôle¶

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 répond 201 avec l'attribution :

{"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 est le nom d'un rôle intégré ou l'identifiant d'un rôle propre.
• Indiquez member_id pour un membre, ou group_id pour un groupe ; chaque membre du groupe a alors le rôle.
• reach vaut organisation (par défaut) ou descendants, voir ci-dessous.

Vous ne pouvez donner qu'un rôle que vous avez vous-même, avec au moins la même portée, ou dont vous avez chaque règle (pourquoi). Un membre a 32 rôles au maximum, member compris.

GET .../role-assignments?member_id=mem_... ou ?group_id=grp_... affiche les rôles d'un membre ou d'un groupe.

Retirer un rôle¶

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

Vous retirez un rôle si vos règles vous permettent de donner ce rôle (use sur le rôle) et si vous pouvez modifier le membre ou le groupe ; que vous ayez ou non le rôle vous-même n'a pas d'importance ici. Une organisation garde toujours au moins un membre actif qui a org-admin lui-même, pas par un groupe. OS refuse avec 409 un retrait qui n'en laisserait aucun ; donnez d'abord org-admin à un autre membre.

Faire valoir un rôle dans les organisations situées en dessous¶

Avec "reach": "descendants", le rôle vaut aussi dans chaque organisation située sous la vôtre. Ainsi, un partenaire donne à ses collaborateurs du support l'accès aux organisations de ses clients, sans qu'ils y deviennent membres. Vous ne pouvez donner cette portée que si vous avez vous-même le rôle avec la portée descendants. OS refuse avec 409 si une organisation en dessous recevait ainsi plus de règles dans les fonctions d'IA qu'elle n'en peut avoir (500), ou plus de 32 attributs et étiquettes.

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

Créer un rôle propre¶

Un rôle propre est un nom avec des règles. Ce rôle permet à un chef d'équipe de voir et de gérer les membres de son propre service :

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

La règle dit : un membre peut voir et modifier un autre membre si un service de ce membre est aussi un service du premier. La façon d'écrire des règles figure dans Types et actions.

• name est unique dans l'organisation et n'est pas le nom d'un rôle intégré, 64 caractères au maximum.
• rules : 200 au maximum, chacune avec 15 conditions au maximum.
• labels est facultatif, comme pour un groupe. L'étiquette builtin appartient aux rôles intégrés.
• Une organisation a 100 rôles propres au maximum.

Un rôle ne peut pas contenir de règles sur memory_write, share_link, artifact_download, router et egress_host (422) : elles valent pour toute l'organisation et figurent dans le document de règles. Une condition nomme role, group, ou un attribut que votre organisation ou une organisation au-dessus a défini.

Vous devez avoir vous-même chaque règle que le rôle autorise. Une règle de refus sur la gestion (organisations, membres, invitations, groupes, rôles, règles et attributs) n'est pas possible ; sur les fonctions d'IA, si.

Modifier ou supprimer un rôle propre¶

Vous remplacez un rôle propre dans son ensemble avec PUT .../roles/rol_... et indiquez la version que vous avez lue dans If-Match, comme pour un groupe. Seules les règles que vous ajoutez sont comparées à ce que vous avez vous-même : vous pouvez modifier un rôle qui contient une règle ajoutée par quelqu'un d'autre. Qui a le rôle relève aussitôt des nouvelles règles.

DELETE .../roles/rol_... supprime le rôle et le retire à tous ceux qui l'avaient. Les rôles intégrés ne se modifient ni ne se suppriment.

Quand OS refuse¶