Manage group membership

Groups are how an organization hands out access: whoever is in a group gets what the group confers. This guide finds the group you want, puts a member into it, checks who is inside, and takes the member out again — four calls.

Before you begin

• An organization-administrator key. Both reading groups and changing their membership are reserved for an organization administrator.

Step 1: Find the group you need

The collection returns the groups your organization has:

GET /groups
Authorization: Bearer YOUR_API_KEY

HTTP/2 200

{
    "total": 4,
    "results": [
        {
            "id": "c4a1f0d2-6b3e-4f28-9a71-5d08e3b7c214",
            "description": "Acme Corporation",
            "type": "organization",
            ...
        },
        {
            "id": "2d90f4a7-15c8-4b3e-8f61-9a04c7e2b5d1",
            "description": "Members who administer the organization",
            "type": "role",
            ...
        },
        {
            "id": "7e52b9c1-8f40-4a6d-b3e9-1c27d5a08f63",
            "description": "Regular organization members",
            "type": "role",
            ...
        },
        {
            "id": "9b41e7c3-0d2a-4f85-b6c9-3e17a504d8f2",
            "description": "Colleagues who work on contracts",
            "type": "visibility",
            ...
        }
    ],
    ...
}

The type tells the three kinds apart. organization is the organization itself, which everybody belongs to. role groups carry the roles — the ones behind the admin and member you set on a user. Everything else, like the visibility group above, is a regular group whose membership is yours to manage.

Each entry also carries displayNames with the group's name translated into the languages your instance supports (omitted here). When you already know a group's identifier, GET /groups/{id} returns that one group on its own.

Step 2: Add a member to the group

The group and the member are both named in the path, and there is no body:

PUT /groups/9b41e7c3-0d2a-4f85-b6c9-3e17a504d8f2/members/jane.doe@example.com
Authorization: Bearer YOUR_API_KEY

HTTP/2 204

The call adds one membership and leaves every other one alone, so a member never loses their organization, their role, or another group by joining this one. Repeating the request on somebody who is already a member answers 204 again and changes nothing.

Step 3: See who is in a group

Group membership is a property of the member, so the user collection answers this one:

GET /users?groupId=9b41e7c3-0d2a-4f85-b6c9-3e17a504d8f2
Authorization: Bearer YOUR_API_KEY

HTTP/2 200

{
    "total": 1,
    "results": [
        {
            "id": "jane.doe@example.com",
            "fullname": "Jane Doe",
            "groupIds": [
                "c4a1f0d2-6b3e-4f28-9a71-5d08e3b7c214",
                "7e52b9c1-8f40-4a6d-b3e9-1c27d5a08f63",
                "9b41e7c3-0d2a-4f85-b6c9-3e17a504d8f2"
            ],
            ...
        }
    ],
    ...
}

groupIds lists every group the member belongs to, the group you filtered by among them. This is the call to reconcile against your own directory before you change anything.

Step 4: Remove a member

Removal mirrors the addition:

DELETE /groups/9b41e7c3-0d2a-4f85-b6c9-3e17a504d8f2/members/jane.doe@example.com
Authorization: Bearer YOUR_API_KEY

HTTP/2 204

The member keeps everything else, including their organization and their role. Removing somebody who is not a member is not an error either — the result is the state you asked for, so 204 says the member is not in the group.

Two memberships cannot be changed this way, and both refuse with 400. The organization itself is one: everyone in it belongs to it, and a member cannot be moved to another organization. A role group is the other — set the member's role instead, as Provision and manage members shows.

Complete example

Bringing a group in line with a list of people from your own system, as a Node.js script. Error handling is minimal for brevity — in production, inspect the error envelope of non-2xx responses.

const BASE_URL = "https://sandbox.circularo.com/api/v1/public"; // your instance's base URL
const API_KEY = "YOUR_API_KEY";
const AUTH_HEADER = { "Authorization": `Bearer ${API_KEY}` };

const groupId = "9b41e7c3-0d2a-4f85-b6c9-3e17a504d8f2";
const shouldBeMembers = ["jane.doe@example.com", "robert.brown@example.com"];

const res = await fetch(`${BASE_URL}/users?groupId=${groupId}&limit=100`, { headers: AUTH_HEADER });
if (!res.ok) throw new Error(`Listing failed: ${res.status}`); // error handling kept minimal for brevity

const current = (await res.json()).results.map((member) => member.id);

for (const id of shouldBeMembers.filter((id) => !current.includes(id))) {
    await fetch(`${BASE_URL}/groups/${groupId}/members/${id}`, { method: "PUT", headers: AUTH_HEADER });
}
for (const id of current.filter((id) => !shouldBeMembers.includes(id))) {
    await fetch(`${BASE_URL}/groups/${groupId}/members/${id}`, { method: "DELETE", headers: AUTH_HEADER });
}

Next steps

• Create the people you are putting into groups — Provision and manage members.

• Confirm who changed what, and when — Search the audit logs.