Manage roles¶

A role decides what someone may do. This page shows how to give a member or a group a role and take it back, how to make a role apply in the organisations below yours, and how to create custom roles. What roles are and which built-in roles exist is in Roles and access.

You give roles with people-admin (only member and people-admin) or org-admin; only org-admin creates, changes and deletes custom roles. Roles have no screen in OS yet: you manage them through the API. The examples use $OS, $TOKEN and $ORG as in Manage groups.

See the roles¶

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

OS lists the built-in roles first, with their name as id (org-admin), then the custom roles, with an id such as rol_.... Every role shows its rules, so GET .../roles/org-admin tells you exactly what a built-in role allows.

Give a role¶

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 answers 201 with the assignment:

{"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 a built-in role's name or a custom role's id.
• Give member_id for one member, or group_id for a group; then every member of the group holds the role.
• reach is organisation (the default) or descendants, see below.

You can only give a role you hold yourself, with at least the same reach, or whose every rule you hold (why). A member holds at most 32 roles, member included.

GET .../role-assignments?member_id=mem_... or ?group_id=grp_... lists the roles of one member or group.

Take a role back¶

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

You take a role back when your rules allow you to give that role (use on the role) and you may change the member or the group; whether you hold the role yourself does not matter here. An organisation always keeps at least one active member who holds org-admin themselves, not through a group. OS refuses a take-back that would leave none with 409; give another member org-admin first.

Make a role apply in the organisations below¶

With "reach": "descendants" the role also applies in every organisation below yours. This is how a partner gives its support people access to its customers' organisations without them becoming members there. You can only give this reach when you hold the role with reach descendants yourself. OS refuses with 409 when an organisation below would then get more rules in the AI features than it may hold (500), or more than 32 attributes and 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"}'

Create a custom role¶

A custom role is a name with rules. This role lets a team lead see and manage the members of their own department:

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

The rule says: a member may see and change another member when one of that member's departments is also one of their own. How to write rules is in Kinds and actions.

• name is unique in the organisation and not the name of a built-in role, at most 64 characters.
• rules: at most 200, each with at most 15 conditions.
• labels are optional, as on a group. The label builtin belongs to the built-in roles.
• An organisation has at most 100 custom roles.

A role cannot hold rules about memory_write, share_link, artifact_download, router and egress_host (422): they apply to the whole organisation and sit in the rules document. A condition names role, group, or an attribute your organisation or an organisation above it has defined.

You must hold every rule the role allows. A refusing rule about administration (organisations, members, invitations, groups, roles, rules and attributes) is not possible; on the AI features it is.

Change or delete a custom role¶

You replace a custom role whole with PUT .../roles/rol_... and name the version you read in If-Match, as for a group. Only the rules you add are checked against what you hold: you can edit a role that holds a rule somebody else added. Whoever holds the role is decided under the new rules at once.

DELETE .../roles/rol_... deletes the role and takes it back from everyone who held it. You do not change or delete built-in roles.

When OS refuses¶