> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/identity-and-access-management-iam/user-groups.md).

# User Groups

Operations for managing user groups including creation, editing, deletion, and listing user groups.

## List all user groups

> This endpoint retrieves a list of user groups and returns their attributes. For possible 'group\_type' values, please refer to the enum documentation for 'GroupType'. Also, 'nested\_groups' refers to the list of direct child groups of the given user group. Similarly, 'idp\_groups' refers to the identifiers of associated identity provider groups to the given user group.

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"tags":[{"name":"User Groups","description":"Operations for managing user groups including creation, editing, deletion, and listing user groups."}],"servers":[{"url":"https://api-{fqdn}","variables":{"fqdn":{"default":"cortex.paloaltonetworks.com","description":"The Fully Qualified Domain Name for the Cortex instance"}}}],"paths":{"/platform/iam/v1/user-group":{"get":{"tags":["User Groups"],"summary":"List all user groups","description":"This endpoint retrieves a list of user groups and returns their attributes. For possible 'group_type' values, please refer to the enum documentation for 'GroupType'. Also, 'nested_groups' refers to the list of direct child groups of the given user group. Similarly, 'idp_groups' refers to the identifiers of associated identity provider groups to the given user group.","operationId":"listUserGroups","responses":{"200":{"description":"Successfully retrieved user groups","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"Metadata":{"type":"object","description":"Metadata for the response","additionalProperties":true}},"responses":{"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object"}}}},"UnauthorizedImproperPermissions":{"description":"Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_msg":{"type":"string"},"err_extra":{"type":"string"},"err_code":{"type":"integer"},"metadata":{"type":"object"}},"required":["err_msg","metadata"]}},"required":["reply"]}}}},"InternalError":{"description":"Internal server error. A unified status for API communication type errors."}}}}
```

## Create a new user group

> This endpoint creates a new user group with the specified configuration. You can assign a role, add users, configure nested groups, and link identity provider groups. All fields except 'group\_name' are optional.

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"tags":[{"name":"User Groups","description":"Operations for managing user groups including creation, editing, deletion, and listing user groups."}],"servers":[{"url":"https://api-{fqdn}","variables":{"fqdn":{"default":"cortex.paloaltonetworks.com","description":"The Fully Qualified Domain Name for the Cortex instance"}}}],"paths":{"/platform/iam/v1/user-group":{"post":{"tags":["User Groups"],"summary":"Create a new user group","description":"This endpoint creates a new user group with the specified configuration. You can assign a role, add users, configure nested groups, and link identity provider groups. All fields except 'group_name' are optional.","operationId":"createUserGroup","requestBody":{"description":"The configuration for the new user group to be created","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserGroupCreateRequest"}}}},"responses":{"201":{"$ref":"#/components/responses/UserGroupCreatedSuccess"},"400":{"$ref":"#/components/responses/UserGroupCreatedBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"UserGroupCreateRequest":{"type":"object","description":"Request object for creating a new user group","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data required to create a new user group","required":["group_name"],"properties":{"group_name":{"type":"string","description":"The unique name for the user group","minLength":1},"role_id":{"type":"string","description":"The unique identifier of the role to assign to this group","nullable":true},"description":{"type":"string","description":"A brief description of the user group's purpose","nullable":true},"users":{"type":"array","items":{"type":"string"},"description":"A list of user email addresses to add to the group","nullable":true},"nested_group_ids":{"type":"array","items":{"type":"string"},"description":"A list of unique identifiers for groups to be nested within this group","nullable":true},"idp_groups":{"type":"array","items":{"type":"string"},"description":"A list of identity provider (IdP) group names to associate with this group","nullable":true}}}},"additionalProperties":false}},"responses":{"UserGroupCreatedSuccess":{"description":"User Group created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the user group was created"}},"required":["message"]}},"required":["data"]}}}},"UserGroupCreatedBadRequest":{"description":"Bad request for user group create call","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"err_msg":{"type":"string","description":"Error message describing the issue"},"metadata":{"type":"object","properties":{"err_extra":{"type":"string","description":"Additional error details"},"err_code":{"type":"integer","description":"HTTP error code"}},"required":["err_extra","err_code"]}},"required":["err_msg","metadata"]}},"required":["data"]}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object"}}}},"UnauthorizedImproperPermissions":{"description":"Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_msg":{"type":"string"},"err_extra":{"type":"string"},"err_code":{"type":"integer"},"metadata":{"type":"object"}},"required":["err_msg","metadata"]}},"required":["reply"]}}}},"InternalError":{"description":"Internal server error. A unified status for API communication type errors."}}}}
```

## Delete an existing user group

> Delete an existing user group. Note: upon deletion of a user group, its nested groups are not deleted; the relationships are simply removed.

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"tags":[{"name":"User Groups","description":"Operations for managing user groups including creation, editing, deletion, and listing user groups."}],"servers":[{"url":"https://api-{fqdn}","variables":{"fqdn":{"default":"cortex.paloaltonetworks.com","description":"The Fully Qualified Domain Name for the Cortex instance"}}}],"paths":{"/platform/iam/v1/user-group/{group_id}":{"delete":{"tags":["User Groups"],"operationId":"deleteUserGroup","parameters":[{"name":"group_id","in":"path","description":"Full user group id","required":true,"schema":{"type":"string"}}],"summary":"Delete an existing user group","description":"Delete an existing user group. Note: upon deletion of a user group, its nested groups are not deleted; the relationships are simply removed.","responses":{"200":{"$ref":"#/components/responses/UserGroupDeletedSuccess"},"400":{"$ref":"#/components/responses/UserGroupDeletedBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"responses":{"UserGroupDeletedSuccess":{"description":"User Group deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the user group was deleted"}},"required":["message"]}},"required":["data"]}}}},"UserGroupDeletedBadRequest":{"description":"Bad request for user group delete call","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"err_msg":{"type":"string","description":"Error message describing the issue"},"metadata":{"type":"object","properties":{"err_extra":{"type":"string","description":"Additional error details"},"err_code":{"type":"integer","description":"HTTP error code"}},"required":["err_extra","err_code"]}},"required":["err_msg","metadata"]}},"required":["data"]}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object"}}}},"UnauthorizedImproperPermissions":{"description":"Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_msg":{"type":"string"},"err_extra":{"type":"string"},"err_code":{"type":"integer"},"metadata":{"type":"object"}},"required":["err_msg","metadata"]}},"required":["reply"]}}}},"InternalError":{"description":"Internal server error. A unified status for API communication type errors."}}}}
```

## Edit an existing user group

> This endpoint allows modification of an existing user group by providing the group\_id in the path and the update details in the request body. Only specified fields will be updated. Please note that to remove attributes, you must provide either an empty string or empty list as the value of the respective field in the request body.

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"tags":[{"name":"User Groups","description":"Operations for managing user groups including creation, editing, deletion, and listing user groups."}],"servers":[{"url":"https://api-{fqdn}","variables":{"fqdn":{"default":"cortex.paloaltonetworks.com","description":"The Fully Qualified Domain Name for the Cortex instance"}}}],"paths":{"/platform/iam/v1/user-group/{group_id}":{"patch":{"tags":["User Groups"],"summary":"Edit an existing user group","description":"This endpoint allows modification of an existing user group by providing the group_id in the path and the update details in the request body. Only specified fields will be updated. Please note that to remove attributes, you must provide either an empty string or empty list as the value of the respective field in the request body.","operationId":"editUserGroup","parameters":[{"name":"group_id","in":"path","description":"Full user group id","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The fields to update for the specified user group","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserGroupEditRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/UserGroupEditedSuccess"},"400":{"$ref":"#/components/responses/UserGroupEditedBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"UserGroupEditRequest":{"type":"object","description":"Request object for editing an existing user group","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data fields to update for the user group","properties":{"group_name":{"type":"string","description":"The new name for the user group","nullable":true},"role_id":{"type":"string","description":"The unique identifier of the new role to assign to this group","nullable":true},"description":{"type":"string","description":"The updated description for the user group","nullable":true},"users":{"type":"array","items":{"type":"string"},"description":"The updated list of user email addresses for the group","nullable":true},"nested_group_ids":{"type":"array","items":{"type":"string"},"description":"The updated list of nested group identifiers","nullable":true},"idp_groups":{"type":"array","items":{"type":"string"},"description":"The updated list of associated identity provider (IdP) group names","nullable":true}}}},"additionalProperties":false}},"responses":{"UserGroupEditedSuccess":{"description":"User Group edited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the user group was edited"}},"required":["message"]}},"required":["data"]}}}},"UserGroupEditedBadRequest":{"description":"Bad request for user group edit call","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"err_msg":{"type":"string","description":"Error message describing the issue"},"metadata":{"type":"object","properties":{"err_extra":{"type":"string","description":"Additional error details"},"err_code":{"type":"integer","description":"HTTP error code"}},"required":["err_extra","err_code"]}},"required":["err_msg","metadata"]}},"required":["data"]}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object"}}}},"UnauthorizedImproperPermissions":{"description":"Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_msg":{"type":"string"},"err_extra":{"type":"string"},"err_code":{"type":"integer"},"metadata":{"type":"object"}},"required":["err_msg","metadata"]}},"required":["reply"]}}}},"InternalError":{"description":"Internal server error. A unified status for API communication type errors."}}}}
```


---

# 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://cortex-docs.paloaltonetworks.com/xsiam-api/identity-and-access-management-iam/user-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.