> 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/xpanse-api/xpanse-public-api/system-management.md).
# System Management
APIs for managing system
## Get Roles
> Retrieve information about one or more roles created in your environment. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json
{"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"System Management","description":"APIs for managing system"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/rbac/get_roles/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRolesResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRolesRequest"}}}},"summary":"Get Roles","tags":["System Management"],"description":"Retrieve information about one or more roles created in your environment.
Required license: **Cortex Xpanse Expander**\n"}}},"components":{"schemas":{"GetRolesResponse":{"type":"object","properties":{"reply":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"description":"JSON object containing the query result."}},"required":["reply"],"additionalProperties":true},"Role":{"type":"object","properties":{"pretty_name":{"type":"string","description":"Name of the role as it appears in the Management Console."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permissions associated with this role."},"insert_time":{"type":"integer","description":"Timestamp of when the Role was created."},"update_time":{"type":"integer","description":"Timestamp of when the Role was last updated."},"created_by":{"type":"string","description":"Email of the user who created the Role."},"description":{"type":"string","description":"Description of the Role, if available."},"groups":{"type":"array","items":{"type":"string"},"description":"Group names associated with the Role."},"users":{"type":"array","items":{"type":"string"},"description":"Email addresses of users associated with the Role."}},"required":["created_by","description","permissions","pretty_name"],"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"GetRolesRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/GetRolesFilter"}},"required":["request_data"],"additionalProperties":true},"GetRolesFilter":{"type":"object","properties":{"role_names":{"type":"array","items":{"type":"string"},"description":"List of one or more role names in your environment for which you want detailed information."}},"additionalProperties":true,"description":"A dictionary containing the API request fields."}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```
## Get Tenant Info
> Get your tenant license information. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json
{"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"System Management","description":"APIs for managing system"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/system/get_tenant_info/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTenantLicenseInfoResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"summary":"Get Tenant Info","tags":["System Management"],"description":"Get your tenant license information.
Required license: **Cortex Xpanse Expander**\n"}}},"components":{"schemas":{"GetTenantLicenseInfoResponse":{"type":"object","properties":{"reply":{"$ref":"#/components/schemas/TenantLicenseInfo"}},"required":["reply"],"additionalProperties":true},"TenantLicenseInfo":{"type":"object","properties":{"aum":{"type":"integer"},"expiration_date":{"type":"string"},"activation_date":{"type":"string"},"status":{"type":"string"}},"required":["activation_date","aum","expiration_date","status"],"additionalProperties":true,"description":"List of available licenses, number of devices, and purchased add-ons on your tenant."},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```
## Get User Groups
> Retrieve a list of the current user emails associated with one or more user groups in your environment. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json
{"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"System Management","description":"APIs for managing system"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/rbac/get_user_group/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserGroupsResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserGroupsRequest"}}}},"summary":"Get User Groups","tags":["System Management"],"description":"Retrieve a list of the current user emails associated with one or more user groups in your environment.
Required license: **Cortex Xpanse Expander**\n"}}},"components":{"schemas":{"GetUserGroupsResponse":{"type":"object","properties":{"reply":{"type":"array","items":{"$ref":"#/components/schemas/UserGroup"},"description":"JSON object containing the query result."}},"required":["reply"],"additionalProperties":true},"UserGroup":{"type":"object","properties":{"group_name":{"type":"string","description":"Name of the User Group."},"description":{"type":"string","description":"Description of the User Group, if available."},"created_by":{"type":"string"},"pretty_name":{"type":"string","description":"Name of the User Group as it appears in the Management Console."},"insert_time":{"type":"integer","description":"Timestamp of when the User Group was created."},"update_time":{"type":"integer","description":"Timestamp of when the User Group was last updated."},"user_email":{"type":"array","items":{"type":"string"},"description":"List of email addresses belonging to the users associated with the User Group."},"source":{"type":"string","description":"Type of User Group."}},"required":["group_name","insert_time","source"],"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"GetUserGroupsRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/GetUserGroupsFilter"}},"required":["request_data"],"additionalProperties":true},"GetUserGroupsFilter":{"type":"object","properties":{"group_names":{"type":"array","items":{"type":"string"},"description":"List of one or more user group names for which you want the associated users."}},"additionalProperties":true,"description":"A dictionary containing the API request fields."}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```
## Get Users
> Retrieve a list of the current users in your environment. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json
{"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"System Management","description":"APIs for managing system"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/rbac/get_users/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUsersResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"summary":"Get Users","tags":["System Management"],"description":"Retrieve a list of the current users in your environment.
Required license: **Cortex Xpanse Expander**\n"}}},"components":{"schemas":{"GetUsersResponse":{"type":"object","properties":{"reply":{"type":"array","items":{"$ref":"#/components/schemas/User"},"description":"JSON object containing the query result."}},"required":["reply"],"additionalProperties":true},"User":{"type":"object","properties":{"user_email":{"type":"string","description":"Email address of the user."},"user_first_name":{"type":"string","description":"First name of the user."},"user_last_name":{"type":"string","description":"Last name of the user."},"role_name":{"type":"string","description":"Role name associated with the user."},"last_logged_in":{"type":"integer","description":"Timestamp of when the user last logged in."},"user_type":{"type":"string","description":"Type of user."},"groups":{"type":"array","items":{"type":"string"},"description":"Name of user groups associated with the user, if applicable."},"scope":{"type":"array","items":{"$ref":"#/components/schemas/Scope"},"description":"Name of scope associated with the user, if applicable."}},"required":["groups","user_email","user_first_name","user_last_name","user_type"],"additionalProperties":true},"Scope":{"type":"object","properties":{"tag_id":{"type":"string"},"tag_name_with_alias":{"type":"string"}},"required":["tag_id","tag_name_with_alias"],"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```
## Set a User role
> Add or remove one or more users from a role. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json
{"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"System Management","description":"APIs for managing system"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/rbac/set_user_role/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetUserRoleResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetUserRoleRequest"}}}},"summary":"Set a User role","tags":["System Management"],"description":"Add or remove one or more users from a role.
Required license: **Cortex Xpanse Expander**\n"}}},"components":{"schemas":{"SetUserRoleResponse":{"type":"object","properties":{"reply":{"$ref":"#/components/schemas/UpdateCountResponse"}},"required":["reply"],"additionalProperties":true},"UpdateCountResponse":{"type":"object","properties":{"update_count":{"type":"integer","description":"Number of updated users."}},"required":["update_count"],"additionalProperties":true,"description":"JSON object containing the query result."},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"SetUserRoleRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/SetUserRoleFilter"}},"required":["request_data"],"additionalProperties":true},"SetUserRoleFilter":{"type":"object","properties":{"user_emails":{"type":"array","items":{"type":"string"},"description":"List of one or more user emails of users you want to add to or remove from a role."},"role_name":{"type":"string","description":"Name of the role you want to add a user to. Send an empty field to remove the user."}},"required":["role_name"],"additionalProperties":true,"description":"A dictionary containing the API request fields."}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```
---
# 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/xpanse-api/xpanse-public-api/system-management.md?ask=&goal=
```
`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.