Groups Endpoints

The Groups API provides endpoints for managing security and distribution groups and their membership.

Base URL

All endpoints are relative to /api/v1/groups.

---

List Groups

Retrieve a paginated list of groups.

GET /api/v1/groups

Query Parameters

Parameter	Type	Description
search	string	Search by group name
limit	number	Number of items to return
after	string	Cursor for pagination

Response

{
  "groups": [
    {
      "id": "grp-123",
      "name": "Engineering Team",
      "description": "All engineering staff",
      "group_type": "security",
      "is_privileged": false,
      "member_count": 45,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "cursor-token"
  }
}

---

Get Group

Retrieve details for a specific group.

GET /api/v1/groups/{id}

Path Parameters

Parameter	Type	Description
id	string	Group ID

Response

Returns the complete group object with all fields.

---

Create Group

Create a new group record.

POST /api/v1/groups

::: note Administrator Only This endpoint requires Administrator role. :::

Request Body

{
  "name": "Finance Team",
  "description": "Finance department members",
  "group_type": "security",
  "is_privileged": false
}

Response

Returns the created group object.

---

Update Group

Update an existing group.

PUT /api/v1/groups/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Group ID

Request Body

Include only the fields to update.

Response

Returns the updated group object.

---

Delete Group

Delete a group record.

DELETE /api/v1/groups/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Group ID

Response

Returns 204 No Content on success.

---

Get Group Members

Retrieve all members of a group with enriched details.

GET /api/v1/groups/{id}/members

Path Parameters

Parameter	Type	Description
id	string	Group ID

Response

{
  "members": [
    {
      "id": "acc-123",
      "name": "john.doe",
      "email": "john.doe@company.com",
      "membership_type": "direct",
      "added_date": "2024-01-10T00:00:00Z",
      "status": "active"
    }
  ],
  "count": 45
}

Membership Types

Type	Description
direct	Member added directly to the group
indirect	Member inherited through nested group

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Group does not exist
500	Internal Server Error

---

Related Topics

• Accounts API - Account management endpoints
• API Reference - Complete API index