---
title: "Admin \u2014 groups & roles"
path: reference/api/admin-groups
status: published
---

# Admin — groups & roles

**4 endpoints** in this group. All paths are prefixed with `/api/v1`.

## Endpoints in this group

- [`GET /api/v1/admin/groups`](#get-api-v1-admin-groups) — List Groups
- [`GET /api/v1/admin/groups/{group_id}`](#get-api-v1-admin-groups-group-id) — Get Group
- [`DELETE /api/v1/admin/groups/{group_id}/role`](#delete-api-v1-admin-groups-group-id-role) — Revoke Group Role
- [`POST /api/v1/admin/groups/{group_id}/role`](#post-api-v1-admin-groups-group-id-role) — Assign Group Role

---

### GET `/api/v1/admin/groups` — List Groups {#get-api-v1-admin-groups}

List all groups with member counts.

**Parameters**:

- `q` (query, string, optional) — Filter by name
- `tenant_id` (query, string, optional)
- `has_role` (query, string, optional) — Filter groups with roles
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_GroupResponse__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/admin/groups/{group_id}` — Get Group {#get-api-v1-admin-groups-group-id}

Get a group with all members.

**Parameters**:

- `group_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_GroupResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### DELETE `/api/v1/admin/groups/{group_id}/role` — Revoke Group Role {#delete-api-v1-admin-groups-group-id-role}

Remove the role from a group.

**Parameters**:

- `group_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_GroupResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/admin/groups/{group_id}/role` — Assign Group Role {#post-api-v1-admin-groups-group-id-role}

Assign a role to a group. All members inherit this role.

**Parameters**:

- `group_id` (path, string, required)
- `authorization` (header, string, optional)


**Body**: `AssignRoleRequest` — {`role`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_GroupResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}