> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups

> API reference for Essal Access group management — create groups, manage membership, and assign roles.

## List Groups

`GET /v1/access/groups`

Returns all groups in the workspace.

***

## Create a Group

`POST /v1/access/groups`

```json theme={null}
{
  "name": "Engineering",
  "description": "All engineering team members",
  "roles": ["office:editor", "project:member"]
}
```

**Response** — `201 Created`

```json theme={null}
{
  "id": "grp_01HXYZGRP1",
  "name": "Engineering",
  "member_count": 0,
  "roles": ["office:editor", "project:member"],
  "created_at": "2026-07-01T08:00:00Z"
}
```

***

## Add Members to a Group

`POST /v1/access/groups/{id}/members`

```json theme={null}
{
  "user_ids": ["usr_01HXYZ1111", "usr_01HXYZ2222", "usr_01HXYZ3333"]
}
```

**Response** — `200 OK`

***

## Remove a Member from a Group

`DELETE /v1/access/groups/{id}/members/{user_id}`

**Response** — `204 No Content`

***

## Update Group Roles

`PATCH /v1/access/groups/{id}`

```json theme={null}
{ "roles": ["office:editor", "project:admin", "sales:viewer"] }
```

Role changes apply immediately to all members of the group.

***

## Delete a Group

`DELETE /v1/access/groups/{id}`

Deletes the group and removes all role assignments derived from group membership. Users are not deleted.

**Response** — `204 No Content`

<Note>
  Members who received roles exclusively through a deleted group will lose those roles immediately. Assign roles directly to affected users if continued access is required.
</Note>