---
title: Groups API
path: reference/api/groups
status: published
---

# Groups API

Reference for the `Groups` endpoint group — 19 endpoints.

Generated from the live OpenAPI spec. Re-run `_generate_api_reference.py` after backend changes.

## Authentication

All endpoints require a Bearer JWT in the `Authorization` header unless noted otherwise. See [Concepts → Tokens and scopes](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/reference/oauth-endpoints) for how to obtain one.

## Endpoints

### **GET** `/api/v1/admin/groups/`

_List Groups_

List groups with filtering.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `search` | query | no | `string` \| `null` |  |
| `tenant_id` | query | no | `string` \| `null` |  |
| `partner_id` | query | no | `string` \| `null` | Filter by partner (all tenants in partner) |
| `group_type` | query | no | `string` \| `null` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/groups/`

_Create Group_

Create a new group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/groups/{group_id}`

_Delete Group_

Soft delete a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/groups/{group_id}`

_Get Group_

Get a group by ID.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PATCH** `/api/v1/admin/groups/{group_id}`

_Update Group_

Update a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/groups/{group_id}/effective-members`

_List Effective Members_

List all effective members of a group, including inherited members from nested groups.

This computes the transitive closure of group memberships.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/groups/{group_id}/members`

_List Group Members_

List members of a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/groups/{group_id}/members`

_Add Group Members_

Add members to a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/groups/{group_id}/members/{user_id}`

_Remove Group Member_

Remove a member from a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `user_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/groups/{group_id}/nested-groups`

_List Nested Groups_

List child groups nested within this group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/groups/{group_id}/nested-groups`

_Add Nested Groups_

Add child groups to nest within this group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/groups/{group_id}/nested-groups/{child_group_id}`

_Remove Nested Group_

Remove a child group from this group's nested groups.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `child_group_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/groups/{group_id}/parent-groups`

_List Parent Groups_

List parent groups that this group is nested within.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `group_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/groups`

_List Groups_

List groups in the tenant directory.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `search` | query | no | `string` \| `null` |  |
| `type` | query | no | [`GroupType`](#schema-grouptype) \| `null` |  |
| `parent_group_id` | query | no | `string` \| `null` |  |
| `user_id` | query | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`PaginatedResponse_GroupListItem_`](#schema-paginatedresponse-grouplistitem) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/groups`

_Create Group_

Create a new group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`GroupCreate`](#schema-groupcreate)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → [`ApiResponse_GroupResponse_`](#schema-apiresponse-groupresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/tenants/{tenant_id}/groups/{group_id}`

_Delete Group_

Delete a group.

strategy:
- BLOCK: Fail if has members or child groups
- ORPHAN: Move child groups to parent
- CASCADE: Delete child groups

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `group_id` | path | yes | `string` |  |
| `strategy` | query | no | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/groups/{group_id}`

_Get Group_

Get a group by ID.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `group_id` | path | yes | `string` |  |
| `include` | query | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_GroupResponse_`](#schema-apiresponse-groupresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PATCH** `/api/v1/tenants/{tenant_id}/groups/{group_id}`

_Update Group_

Update a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `group_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`GroupUpdate`](#schema-groupupdate)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_GroupResponse_`](#schema-apiresponse-groupresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PUT** `/api/v1/tenants/{tenant_id}/groups/{group_id}/members`

_Update Group Members_

Add or remove users from a group.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `group_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`GroupMembershipUpdate`](#schema-groupmembershipupdate)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## Schemas

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

### `ApiResponse_GroupResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`GroupResponse`](#schema-groupresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `GroupCreate`

Schema for creating a group.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `description` | `string` \| `null` | no |  |
| `group_type` | [`GroupType`](#schema-grouptype) | no | Default: `SECURITY` |
| `parent_group_id` | `string` \| `null` | no |  |
| `initial_members` | array of `string` | no |  |
| `custom_attributes` | object \| `null` | no |  |

### `GroupListItem`

Abbreviated group info for lists.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `group_type` | [`GroupType`](#schema-grouptype) | yes |  |
| `member_count` | `integer` | no | Default: `0` |
| `parent_group_id` | `string` \| `null` | no |  |

### `GroupMemberInfo`

Member info within a group.

| Field | Type | Required | Description |
|---|---|---|---|
| `user_id` | `string` | yes |  |
| `email` | `string` | yes |  |
| `display_name` | `string` \| `null` | no |  |
| `membership_type` | `string` | no | Default: `DIRECT` |

### `GroupMembershipUpdate`

Schema for updating group membership.

| Field | Type | Required | Description |
|---|---|---|---|
| `users_to_add` | array of `string` | no |  |
| `users_to_remove` | array of `string` | no |  |

### `GroupResponse`

Full group response.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `description` | `string` \| `null` | no |  |
| `group_type` | [`GroupType`](#schema-grouptype) | no | Default: `SECURITY` |
| `id` | `string` | yes |  |
| `parent_group_id` | `string` \| `null` | no |  |
| `parent_group_path` | `string` \| `null` | no |  |
| `member_count` | `integer` | no | Default: `0` |
| `effective_member_count` | `integer` \| `null` | no |  |
| `nested_group_count` | `integer` | no | Default: `0` |
| `members` | array of [`GroupMemberInfo`](#schema-groupmemberinfo) \| `null` | no |  |
| `nested_groups` | array of [`NestedGroupInfo`](#schema-nestedgroupinfo) \| `null` | no |  |
| `custom_attributes` | object \| `null` | no |  |
| `created_at` | `string` (`date-time`) | yes |  |
| `updated_at` | `string` (`date-time`) \| `null` | no |  |

### `GroupType`

Group type.

**Type:** `string` (enum)

**Values:** `SECURITY`, `DISTRIBUTION`

### `GroupUpdate`

Schema for updating a group.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` \| `null` | no |  |
| `description` | `string` \| `null` | no |  |
| `parent_group_id` | `string` \| `null` | no |  |
| `custom_attributes` | object \| `null` | no |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `MetaResponse`

Metadata included in API responses.

| Field | Type | Required | Description |
|---|---|---|---|
| `request_id` | `string` \| `null` | no |  |
| `timestamp` | `string` (`date-time`) | no |  |

### `NestedGroupInfo`

Nested group info.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `member_count` | `integer` | no | Default: `0` |

### `PaginatedResponse_GroupListItem_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [`GroupListItem`](#schema-grouplistitem) | yes |  |
| `pagination` | [`PaginationMeta`](#schema-paginationmeta) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `PaginationMeta`

Pagination metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | `integer` | yes |  |
| `per_page` | `integer` | yes |  |
| `total_items` | `integer` | yes |  |
| `total_pages` | `integer` | yes |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |