Manage groups¶

A group gives a whole team the same roles and attributes at once. This page shows how to create a group, add and remove members and delete a group again. What a group is, is in Roles and access.

You manage groups with the role people-admin or org-admin; only org-admin deletes a group. Groups have no screen in OS yet: you manage them through the API.

Before you start¶

The examples use three variables in your shell:

OS=https://os.example.com      # the address of OS
TOKEN=...                      # an access token from your own sign-in
ORG=org_...                    # your organisation's id

How a request to OS works, and what every answer carries, is in The access API.

Create a group¶

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

OS answers 201 with the group:

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

• name is unique in the organisation, at most 200 characters.
• labels are optional: labels that rules about groups can read, at most 32. A label holds one value or a list of values.

GET /api/v1/organisations/$ORG/groups lists the groups you may see, in pages of at most 200 (limit, 50 by default); pass next_cursor as cursor for the next page.

Rename or relabel a group¶

You replace the group whole and name the version you read. It is in version and in the ETag header of the answer.

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

If someone changed the group in the meantime, OS answers 409. Read the group again and repeat your change.

Add and remove members¶

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

The member gets every role and value of the group at once. That is why you must yourself hold every role and every value the group gives; otherwise OS refuses with 403 and names what you lack (why).

• GET .../groups/grp_.../members lists the members you may see.
• DELETE .../groups/grp_.../members/mem_... takes a member out of the group. The member loses what the group gave, and keeps what they hold themselves or through other groups.

A member is in at most 32 groups.

Give a group roles or attributes¶

A group gets a role the way a member does, with group_id instead of member_id: see Give a role and Give a value.

Delete a group¶

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

OS answers 204. The members lose what the group gave. Roles and values they hold themselves stay.

When OS refuses¶