Groups API: Directory Groups and Role Mappings - OneCLI

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. See User provisioning for the bigger picture.

Endpoints

Endpoint	Method and path	What it does
List groups	`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	`POST /org/groups`	Create a directory group to manage members together and map them to a role.
Get a group	`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	`PATCH /org/groups/{groupId}`	Rename a directory group.
Delete a group	`DELETE /org/groups/{groupId}`	Delete a directory group.
List a group’s members	`GET /org/groups/{groupId}/members`	List the members of a directory group.
Replace a group’s members	`PUT /org/groups/{groupId}/members`	Replace a directory group’s full member list in one call.
Add a member to a group	`PUT /org/groups/{groupId}/members/{userId}`	Add one member to a directory group.
Remove a member from a group	`DELETE /org/groups/{groupId}/members/{userId}`	Remove one member from a directory group.
List group-to-role mappings	`GET /org/role-mappings`	List group-to-role mappings, highest priority first.
Create a role mapping	`POST /org/role-mappings`	Map a directory group to an organization role.
Reorder role mappings	`PUT /org/role-mappings/order`	Reorder role mappings by priority.
Preview a role mapping’s impact	`POST /org/role-mappings/preview`	Preview a role mapping before saving it.
Update a role mapping	`PATCH /org/role-mappings/{id}`	Update a group-to-role mapping, such as the role it grants.
Delete a role mapping	`DELETE /org/role-mappings/{id}`	Delete a group-to-role mapping.

Next steps

API overview: base URLs, authentication, and pagination
Errors: status codes and the error format
Editions: which endpoints each edition serves