---
title: "Groups"
description: "Create directory groups, manage their members, and use them in assignments and the groups claim."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups

A directory group is a set of directory users. Use groups to [assign](/sso/assignments) people to
applications, and to tell applications what people belong to: the `groups` claim carries group
names. Directory groups are separate from IAM groups, which hold members.

## Group fields

| Field | Description |
| --- | --- |
| `id`, `slug`, `resourceName` | The group's ID (a UUID), slug (`dgp_…`) and resource name, `ezgh:us-west-1:org_…:dir_…:dgp_…`. |
| `name` | 1 to 128 characters, unique in the directory (`409 group_name_taken`). Applications see it in the `groups` claim. |
| `description` | Up to 1,024 characters. |
| `tags` | Up to 50 key-value pairs, as for the directory. |
| `memberCount` | How many users are in the group. |
| `source` | `hosted` (created by you) or `scim` (pushed by your identity provider's [SCIM](/sso/scim)). |
| `locked` | `true` while the group's identity provider manages it over SCIM: renaming it, deleting it and changing its members are then `409 managed_by_scim`. |

## Create and change groups

```sh
ezgh sso groups create engineering --description "Everyone in engineering"
ezgh sso groups add-members engineering ada@acme.com grace@acme.com
ezgh sso groups members engineering
```

API: [CreateGroup](/sso-api/CreateGroup/), [UpdateGroup](/sso-api/UpdateGroup/),
[DeleteGroup](/sso-api/DeleteGroup/), [ListGroupMembers](/sso-api/ListGroupMembers/),
[AddGroupMembers](/sso-api/AddGroupMembers/) and
[RemoveGroupMembers](/sso-api/RemoveGroupMembers/).

- Member changes take `{ "userIds": [...] }`, 1 to 100 user IDs at a time. Adding a user who is
  already a member, or removing one who isn't, changes nothing. Every ID must be a user of the
  directory, or the request is `400`.
- Group responses carry an `ETag`, which covers the name, description, tags and members. Updates,
  deletes and member changes take `If-Match`: if the group changed since you read it, the request
  is `412 precondition_failed` and nothing changes. Without `If-Match` the change applies.
- Deleting a group removes its memberships and its [assignments](/sso/assignments).
- An [identity provider's group mappings](/sso/identity-providers#group-mappings) can add people
  to groups you created when they sign in.
- You can add users provisioned by SCIM to groups you created. A group's name is unique in the
  directory, whether you created it or SCIM pushed it.

Membership changes apply at once: the next token an application gets, and every
[assignment](/sso/assignments) check, use the current members.

Source: https://docs.ezghcloud.com/sso/groups/index.mdx