> 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/xdr-5-api/identity-and-access-management-iam/roles.md).

# Roles

Operations for managing roles including creation, editing, deletion, and listing roles.

## List all roles

> This endpoint retrieves a list of roles and returns their attributes. This API does not list permissions for said roles. To receive that information, please leverage the existing \[Get-Roles]\(<https://app.gitbook.com/s/FK89utN7l3ilSek2DmU5/cortex-platform/system-management#post-public\\_api-v1-rbac-get\\_roles>) API. Note: 'role\_id' refers to the immutable role ID, while 'pretty\_name' refers to the display name.

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XDR 5.1"},"tags":[{"name":"Roles","description":"Operations for managing roles including creation, editing, deletion, and listing roles."}],"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/role":{"get":{"tags":["Roles"],"summary":"List all roles","description":"This endpoint retrieves a list of roles and returns their attributes. This API does not list permissions for said roles. To receive that information, please leverage the existing [Get-Roles](https://app.gitbook.com/s/FK89utN7l3ilSek2DmU5/cortex-platform/system-management#post-public_api-v1-rbac-get_roles) API. Note: 'role_id' refers to the immutable role ID, while 'pretty_name' refers to the display name.","operationId":"listRoles","responses":{"200":{"description":"Successfully retrieved roles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"Role":{"type":"object","properties":{"role_id":{"type":"string","description":"The unique identifier for the role"},"pretty_name":{"type":"string","description":"The display name for the role"},"description":{"type":"string","description":"A description of the role's purpose and permissions","nullable":true},"is_custom":{"type":"boolean","description":"Indicates if the role is a custom role (true) or a predefined system role (false)"},"created_by":{"type":"string","description":"The user or system that created the role"},"created_ts":{"type":"integer","description":"The timestamp when the role was created","nullable":true},"updated_ts":{"type":"integer","description":"The timestamp when the role was last updated","nullable":true}},"required":["role_id","pretty_name","description","is_custom","created_by","created_ts","updated_ts"]},"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 role

> To identify all potential permissions that can be entered into the 'component\_permissions' field, please utilize the 'GET /platform/iam/v1/role/permission-config' endpoint and utilize the 'view\_name' and 'action\_name' properties. Note: if you input an 'action' permission, then the relevant 'view' permission will be added for you. There will also be checks done on sub-permissions, ensuring that the main 'action' permissions are present as well. The available datasets can also be found by utilizing the 'GET /platform/iam/v1/role/permission-config' endpoint. Any dataset related permissions are not permissible in the 'component\_permissions' field (an error will be thrown). The 'permissions' field in the entry for 'dataset\_permissions' refers to dataset names for said dataset category.It is important to note that the 'access\_all' field will only grant the role access to all datasets in said category that the API key has access to.

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XDR 5.1"},"tags":[{"name":"Roles","description":"Operations for managing roles including creation, editing, deletion, and listing roles."}],"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/role":{"post":{"tags":["Roles"],"summary":"Create a new role","description":"To identify all potential permissions that can be entered into the 'component_permissions' field, please utilize the 'GET /platform/iam/v1/role/permission-config' endpoint and utilize the 'view_name' and 'action_name' properties. Note: if you input an 'action' permission, then the relevant 'view' permission will be added for you. There will also be checks done on sub-permissions, ensuring that the main 'action' permissions are present as well. The available datasets can also be found by utilizing the 'GET /platform/iam/v1/role/permission-config' endpoint. Any dataset related permissions are not permissible in the 'component_permissions' field (an error will be thrown). The 'permissions' field in the entry for 'dataset_permissions' refers to dataset names for said dataset category.It is important to note that the 'access_all' field will only grant the role access to all datasets in said category that the API key has access to.","operationId":"createRole","requestBody":{"description":"The configuration for the new role to be created","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleCreateRequest"}}}},"responses":{"201":{"$ref":"#/components/responses/RoleCreatedSuccess"},"400":{"$ref":"#/components/responses/RoleCreatedBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"RoleCreateRequest":{"type":"object","description":"Request object for creating a new role","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data required to create a new role","required":["component_permissions","pretty_name"],"properties":{"component_permissions":{"type":"array","items":{"type":"string"},"description":"List of component permissions for the role. Possible values can be found by using the permission configs API and referring to the `rbac_permissions` field.","minItems":1},"dataset_permissions":{"type":"array","items":{"type":"object"},"description":"Optional list of dataset permissions. This must be a list of JSONs. The layout for this JSON can be found under the 'DatasetPermission' schema . Note: possible dataset values can be found by using the permission configs API and referring to the `datasetGroups` field.","nullable":true},"pretty_name":{"type":"string","description":"Name of the role","minLength":1},"description":{"type":"string","description":"Optional description of the role","nullable":true}}}},"additionalProperties":false}},"responses":{"RoleCreatedSuccess":{"description":"Role created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the role was created"}},"required":["message"]}},"required":["data"]}}}},"RoleCreatedBadRequest":{"description":"Bad request for role 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 role

> Delete an existing Role

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XDR 5.1"},"tags":[{"name":"Roles","description":"Operations for managing roles including creation, editing, deletion, and listing roles."}],"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/role/{role_id}":{"delete":{"tags":["Roles"],"parameters":[{"name":"role_id","in":"path","description":"Full role id of the custom role","required":true,"schema":{"type":"string"}}],"summary":"Delete an existing role","description":"Delete an existing Role","operationId":"deleteRole","responses":{"200":{"$ref":"#/components/responses/RoleDeletedSuccess"},"400":{"$ref":"#/components/responses/RoleDeletedBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/UnauthorizedImproperPermissions"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"responses":{"RoleDeletedSuccess":{"description":"Role deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the role was deleted"}},"required":["message"]}},"required":["data"]}}}},"RoleDeletedBadRequest":{"description":"Bad request for role 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."}}}}
```

## List all permission configs

> Returns the current list of permissions available for the specified tenant. \
> Each permission includes:\
> \- \*\*name:\*\* Display name of the permission as shown in the UI.  \
> \- \*\*view\_name:\*\* Permission key for the "View" option, used in role creation APIs.  \
> \- \*\*action\_name:\*\* Permission key for the "View/Edit" option, used in role creation APIs.  \
> \
> \*\*Intended use:\*\*  Use this endpoint to identify the correct permission keys corresponding to the display names visible in the UI.  \
> Note - The response mirrors how permissions are organized and displayed in the UI (by category and subcategory).

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XDR 5.1"},"tags":[{"name":"Roles","description":"Operations for managing roles including creation, editing, deletion, and listing roles."}],"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/role/permission-config":{"get":{"tags":["Roles"],"summary":"List all permission configs","description":"Returns the current list of permissions available for the specified tenant. \nEach permission includes:\n- **name:** Display name of the permission as shown in the UI.  \n- **view_name:** Permission key for the \"View\" option, used in role creation APIs.  \n- **action_name:** Permission key for the \"View/Edit\" option, used in role creation APIs.  \n\n**Intended use:**  Use this endpoint to identify the correct permission keys corresponding to the display names visible in the UI.  \nNote - The response mirrors how permissions are organized and displayed in the UI (by category and subcategory).","operationId":"listPermissionConfigs","responses":{"200":{"description":"Successfully retrieved permission configs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"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."}}}}
```


---

# 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/xdr-5-api/identity-and-access-management-iam/roles.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.