role_controller¶

The following methods allow for interaction with the ZPA Role Controller API endpoints.

Methods are accessible via zpa.role_controller

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class RoleControllerAPI¶

Bases: APIClient

A client object for the Role Controller resource.

add_role(**kwargs)¶

Adds a new role.

Note

To retrieve the class_permission_groups and required permission IDs, use the list_permission_groups() method.

Parameters:

name (str) – The name of the role.
description (str) – The description of the role.
bypass_remote_assistance_check (bool) – Whether to bypass remote assistance check.
class_permission_groups (list) – A list of permission group dictionaries.

:keyword : param dict class_permission_groups[]: Each dictionary represents a permission group :keyword : param str class_permission_groups[].id: ID of the permission group :keyword : param str class_permission_groups[].name: Name of the permission group :keyword : param bool class_permission_groups[].local_scope_permission_group: Whether the group is scoped locally :keyword : param list class_permission_groups[].class_permissions: A list of permission entries :keyword : param dict class_permission_groups[].class_permissions[].permission: Must include a “type” key :keyword : param str class_permission_groups[].class_permissions[].permission.type: Allowed values: “VIEW_ONLY”, “FULL” :keyword : param dict class_permission_groups[].class_permissions[].class_type: Must include an “id” key :keyword : param str class_permission_groups[].class_permissions[].class_type.id: ID representing the class type

Returns:

A tuple containing:

RoleController: The created role object.
HTTP response object.
Error object, if any.

Return type:

tuple

Example

>>> added_role, _, err = zpa.role_controller.add_role(
...     name="Example Group",
...     description="This is an example segment group.",
...     bypass_remote_assistance_check=False,
...     class_permission_groups=[
...         {
...             "id": "10",
...             "name": "Administration",
...             "local_scope_permission_group": True,
...             "class_permissions": [
...                 {
...                     "permission": {"type": "FULL"},
...                     "class_type": {"id": "11"}
...                 },
...                 {
...                     "permission": {"type": "VIEW_ONLY"},
...                     "class_type": {"id": "3"}
...                 }
...             ]
...         }
...     ]
... )

>>> added_role, _, err = zpa.role_controller.add_role(
...     name="Microtenant Role",
...     description="Role for microtenant access",
...     bypass_remote_assistance_check=False,
...     microtenant_id="216196257331380392",
...     class_permission_groups=[{...}]
... )

delete_role(role_id, microtenant_id=None)¶

Deletes the specified role.

Parameters:: role_id (str) – The unique identifier for the role to be deleted.
Returns:: Status code of the delete operation.
Return type:: int

Example

Delete a role by ID >>> _, _, err = client.zpa.role_controller.delete_role(‘2445851154’) … if err: … print(f”Error deleting role: {err}”) … return … print(f”Role with ID {‘2445851154’} deleted successfully.”)

get_role(role_id, query_params=None)¶

Gets information on the specified role by ID.

Parameters:

role_id (str) – The unique identifier of the role.
query_params (dict, optional) – Map of query parameters for the request. [query_params.microtenant_id] {str}: The microtenant ID, if applicable.

Returns:

RoleController: The corresponding role object.

Return type:

Tuple

Example

Retrieve details of a specific role

>>> fetched_role, _, err = client.zpa.role_controller.get_role('999999')
... if err:
...     print(f"Error fetching role by ID: {err}")
...     return
... print(f"Fetched role by ID: {fetched_role.as_dict()}")

list_permission_groups(query_params=None)¶

Get All the default permission groups

Parameters:: {dict} (query_params) – Map of query parameters for the request. [query_params.microtenant_id] {str}: ID of the microtenant, if applicable.
Returns:: A tuple containing (list of ClassPermissionGroups instances, Response, error)
Return type:: Tuple

Example

Fetch all default permission groups

>>> permission_groups, _, err = client.zpa.role_controller.list_permission_groups()
>>> if err:
...     print(f"Error listing permission groups: {err}")
...     return
... for group in permission_groups:
...     print(group.as_dict())

list_roles(query_params=None)¶

Get All configured roles.

Parameters:: {dict} (query_params) – Map of query parameters for the request. [query_params.microtenant_id] {str}: ID of the microtenant, if applicable.
Returns:: A tuple containing (list of RoleController instances, Response, error)
Return type:: Tuple

Example

Fetch all roles without filtering

>>> role_list, _, err = client.zpa.role_controller.list_roles()
... if err:
...     print(f"Error listing roles: {err}")
...     return
... print(f"Total roles found: {len(role_list)}")
... for role in role_list:
...     print(role.as_dict())

update_role(role_id, **kwargs)¶

Updates the specified role.

Parameters:

role_id (str) – The unique identifier for the role being updated.
name (str) – The name of the role.
description (str) – The description of the role.
bypass_remote_assistance_check (bool) – Whether to bypass remote assistance check.
class_permission_groups (list) – A list of permission group dictionaries.

Returns:

A tuple containing:

RoleController: The created role object.
Response: The raw HTTP response.
Error: Any error returned.

Return type:

tuple

Example

Basic example: Add a new role

>>> updated_role, _, err = zpa.role_controller.update_role(
...     role_id='98877899',
...     name="Example Group",
...     description="This is an example segment group.",
...     bypass_remote_assistance_check=False,
...     class_permission_groups=[
...         {
...             "id": "10",
...             "name": "Administration",
...             "local_scope_permission_group": True,
...             "class_permissions": [
...                 {
...                     "permission": {"type": "FULL"},
...                     "class_type": {"id": "11"}
...                 },
...                 {
...                     "permission": {"type": "VIEW_ONLY"},
...                     "class_type": {"id": "3"}
...                 }
...             ]
...         }
...     ]
... )

Adding a role for a specific microtenant:

>>> updated_role, _, err = zpa.role_controller.update_role(
...     role_id='98877899',
...     name="Microtenant Role",
...     description="Role for microtenant access",
...     bypass_remote_assistance_check=False,
...     microtenant_id="216196257331380392",
...     class_permission_groups=[{...}]
... )