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

# Groups API: Directory Groups and Role Mappings

> Create directory groups, manage their members, and map groups to roles with the OneCLI API. Preview role changes before you save.

Groups collect members so you can manage access together. Role mappings connect a group to an organization role, so everyone in the group gets that role automatically.

On Cloud, groups need the Enterprise plan. To sync groups from an identity provider, use [SCIM](https://onecli.sh/docs/api-reference/scim). See [User provisioning](https://onecli.sh/docs/guides/user-provisioning.md) for the bigger picture.

## Related guides

* [User provisioning: groups and roles](https://onecli.sh/docs/guides/user-provisioning.md)
* [Editions: which plans include groups](https://onecli.sh/docs/api-reference/editions.md)

## Endpoints

| Endpoint | Method and path | What it does |
| - | - | - |
| [List groups](https://onecli.sh/docs/api-reference/groups/list-groups.md) | `GET /org/groups` | List your organization's directory groups with cursor pagination, including groups created by hand and groups synced over SCIM. |
| [Create a group](https://onecli.sh/docs/api-reference/groups/create-a-group.md) | `POST /org/groups` | Create a directory group to manage members together and map them to a role. |
| [Get a group](https://onecli.sh/docs/api-reference/groups/get-a-group.md) | `GET /org/groups/{groupId}` | Get one directory group by ID, including its name and source, so you can check it before you change its members or mappings. |
| [Rename a group](https://onecli.sh/docs/api-reference/groups/rename-a-group.md) | `PATCH /org/groups/{groupId}` | Rename a directory group. |
| [Delete a group](https://onecli.sh/docs/api-reference/groups/delete-a-group.md) | `DELETE /org/groups/{groupId}` | Delete a directory group. |
| [List a group's members](https://onecli.sh/docs/api-reference/groups/list-a-groups-members.md) | `GET /org/groups/{groupId}/members` | List the members of a directory group. |
| [Replace a group's members](https://onecli.sh/docs/api-reference/groups/replace-a-groups-members.md) | `PUT /org/groups/{groupId}/members` | Replace a directory group's full member list in one call. |
| [Add a member to a group](https://onecli.sh/docs/api-reference/groups/add-a-member-to-a-group.md) | `PUT /org/groups/{groupId}/members/{userId}` | Add one member to a directory group. |
| [Remove a member from a group](https://onecli.sh/docs/api-reference/groups/remove-a-member-from-a-group.md) | `DELETE /org/groups/{groupId}/members/{userId}` | Remove one member from a directory group. |
| [List group-to-role mappings](https://onecli.sh/docs/api-reference/groups/list-group-to-role-mappings.md) | `GET /org/role-mappings` | List group-to-role mappings, highest priority first. |
| [Create a role mapping](https://onecli.sh/docs/api-reference/groups/create-a-role-mapping.md) | `POST /org/role-mappings` | Map a directory group to an organization role. |
| [Reorder role mappings](https://onecli.sh/docs/api-reference/groups/reorder-role-mappings.md) | `PUT /org/role-mappings/order` | Reorder role mappings by priority. |
| [Preview a role mapping's impact](https://onecli.sh/docs/api-reference/groups/preview-a-role-mappings-impact.md) | `POST /org/role-mappings/preview` | Preview a role mapping before saving it. |
| [Update a role mapping](https://onecli.sh/docs/api-reference/groups/update-a-role-mapping.md) | `PATCH /org/role-mappings/{id}` | Update a group-to-role mapping, such as the role it grants. |
| [Delete a role mapping](https://onecli.sh/docs/api-reference/groups/delete-a-role-mapping.md) | `DELETE /org/role-mappings/{id}` | Delete a group-to-role mapping. |

## Next steps

* [API overview](https://onecli.sh/docs/api-reference.md): base URLs, authentication, and pagination
* [Errors](https://onecli.sh/docs/api-reference/errors.md): status codes and the error format
* [Editions](https://onecli.sh/docs/api-reference/editions.md): which endpoints each edition serves


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.