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 and 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`

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`

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`

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`

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`

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
`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`

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

List Group Members

List members of a group.

Parameters:

Name	In	Required	Type
`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`

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`

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

Remove Group Member

Remove a member from a group.

Parameters:

Name	In	Required	Type
`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`

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

List Nested Groups

List child groups nested within this group.

Parameters:

Name	In	Required	Type
`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`

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`

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
`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`

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
`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`

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

List Groups

List groups in the tenant directory.

Parameters:

Name	In	Required	Type
`tenant_id`	path	yes	`string`
`page`	query	no	`integer`
`per_page`	query	no	`integer`
`search`	query	no	`string` \| `null`
`type`	query	no	`GroupType` \| `null`
`parent_group_id`	query	no	`string` \| `null`
`user_id`	query	no	`string` \| `null`

Responses:

Status	Body
`200`	`application/json` → `PaginatedResponse_GroupListItem_`
`422`	`application/json` → `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

Responses:

Status	Body
`201`	`application/json` → `ApiResponse_GroupResponse_`
`422`	`application/json` → `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
`tenant_id`	path	yes	`string`
`group_id`	path	yes	`string`
`strategy`	query	no	`string`

Responses:

Status	Body
`204`	Successful Response
`422`	`application/json` → `HTTPValidationError`

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

Get Group

Get a group by ID.

Parameters:

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

Responses:

Status	Body
`200`	`application/json` → `ApiResponse_GroupResponse_`
`422`	`application/json` → `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

Responses:

Status	Body
`200`	`application/json` → `ApiResponse_GroupResponse_`
`422`	`application/json` → `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

Responses:

Status	Body
`200`	`application/json` → any
`422`	`application/json` → `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`	yes
`meta`	`MetaResponse`	no

`GroupCreate`#

Schema for creating a group.

Field	Type	Required	Description
`name`	`string`	yes
`description`	`string` \| `null`	no
`group_type`	`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`	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`	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` \| `null`	no
`nested_groups`	array of `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
`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`	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
`data`	array of `GroupListItem`	yes
`pagination`	`PaginationMeta`	yes
`meta`	`MetaResponse`	no

`PaginationMeta`#

Pagination metadata.

Field	Type	Required
`page`	`integer`	yes
`per_page`	`integer`	yes
`total_items`	`integer`	yes
`total_pages`	`integer`	yes

`ValidationError`#

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

Groups API

Authentication#

Endpoints#

GET /api/v1/admin/groups/#

POST /api/v1/admin/groups/#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schemas#

ApiResponse_GroupResponse_#

GroupCreate#

GroupListItem#

GroupMemberInfo#

GroupMembershipUpdate#

GroupResponse#

GroupType#

GroupUpdate#

HTTPValidationError#

MetaResponse#

NestedGroupInfo#

PaginatedResponse_GroupListItem_#

PaginationMeta#

ValidationError#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`ApiResponse_GroupResponse_`#

`GroupCreate`#

`GroupListItem`#

`GroupMemberInfo`#

`GroupMembershipUpdate`#

`GroupResponse`#

`GroupType`#

`GroupUpdate`#

`HTTPValidationError`#

`MetaResponse`#

`NestedGroupInfo`#

`PaginatedResponse_GroupListItem_`#

`PaginationMeta`#

`ValidationError`#