> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/setup/working-with-groups.md).

# Working with groups

A **group** bundles users for scalable role assignment. Assigning a role to ten users one by one is tedious and drift-prone; assigning a role to a group of ten users is one action and stays correct as the group's membership shifts. Groups are the right unit for any role you assign more than once.

### Creating a group

#### Create a group

**Before you start**

* A display name and a slug. The display name is operator-facing; the slug is the machine-readable identifier used in audit logs and API responses. The slug is permanent.
* The `group.create` permission. If **Create group** is disabled, your role lacks the permission.
* A plan for which roles the group will carry. The form does not require role assignment at creation, but a group with no roles grants no permissions; assign roles from the group detail page after creation.

To create a group:

1. From the left sidebar, choose **Setup** → **Groups** → **Create group**. The portal opens the **Create group** modal.
2. Enter a **Display Name** (required), a **Name** (the slug, required and permanent; use lower-case-with-hyphens such as `api-platform`), and an optional **Description**.
3. Click **Create group**.

![Figure 16-1. The Create group dialog.](/files/F0y9aaDEW3aZ9Ae4L7b9)

The numbered callouts in Figure 16-1 are:

1. **Display Name.** Operator-facing label. Required.
2. **Name.** Permanent slug used internally. Required.
3. **Description.** Optional context.
4. **Cancel** and **Create group.** Modal actions.

**Verify**

1. The modal closes and the group appears at the top of the **Groups** list.
2. The **TYPE** column shows the default for portal-created groups.
3. The **ROLES** column reads `0` until roles are assigned.

{% hint style="success" %}
**Result:** The group exists, ready to receive members and roles.
{% endhint %}

{% hint style="danger" %}
**Caution:** The slug is permanent. It appears in the audit log, in API responses, and in user-search filters. Pick a slug you are happy to live with for the life of the organisation.
{% endhint %}

{% hint style="success" %}
**Tip:** Provision groups *before* invitations begin. Inviting users without a target group means a separate group-membership step per user; with groups in place first, you assign on invitation acceptance.
{% endhint %}

Related tasks:

* [Defining roles and permissions](/api-gateway/setup/defining-roles-and-permissions.md#defining-roles-and-permissions): author the roles to assign.
* [Inviting and managing users](/api-gateway/setup/inviting-and-managing-users.md#inviting-and-managing-users): add users to the group as you invite them.

### Reading the groups list

#### Browse and filter groups

To browse:

1. From the left sidebar, choose **Setup** → **Groups** (`/organization/groups`).
2. Filter with **Search groups...**.
3. Click **All groups** to widen the view after a filter.

![Figure 16-2. The Groups list.](/files/SEUHVbjUvwg1PsiaO4Sk)

Table 16-A. Columns on the Groups list.

| Column    | What it shows                               |
| --------- | ------------------------------------------- |
| **Name**  | Display name.                               |
| **TYPE**  | Portal-created or identity-provider-synced. |
| **ROLES** | Count of roles assigned.                    |

**Verify**

1. The URL is `<your-helix-portal-domain>/organization/groups`.
2. **Create group** is visible at the top right.

{% hint style="success" %}
**Result:** A group inventory, two clicks from any group.
{% endhint %}

Related tasks:

* [Create a group](#create-a-group): author a new group.
* [Defining roles and permissions](/api-gateway/setup/defining-roles-and-permissions.md#defining-roles-and-permissions): assign roles to the group.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digitalapi.ai/api-gateway/setup/working-with-groups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.