groups¶

The following methods allow for interaction with the Zidentity Groups API endpoints.

Methods are accessible via zidentity.groups

Pagination¶

The Zidentity Groups API supports pagination with a maximum page size of 100 records per request. The SDK automatically handles pagination for all groups endpoints.

Key Features: - Maximum Page Size: 100 records per page (enforced by API) - Automatic Pagination: SDK handles pagination transparently - Response Format: Returns data in records field with pagination metadata

Example Usage:

from zscaler import ZscalerClient

config = {
    "clientId": '{yourClientId}',
    "clientSecret": '{yourClientSecret}',
    "vanityDomain": '{yourvanityDomain}',
    "cloud": "beta",
}

def main():
    with ZscalerClient(config) as client:
        # Request 300 groups (will automatically fetch 3 pages)
        groups_response, response, error = client.zidentity.groups.list_groups(
            query_params={'page_size': 300}
        )

        if error:
            print(f"Error listing groups: {error}")
            return

        print(f"Total groups in response: {len(groups_response.records)}")
        print(f"Total available: {groups_response.results_total}")
        print(f"Page offset: {groups_response.page_offset}")
        print(f"Page size: {groups_response.page_size}")

        # Access individual groups
        for group in groups_response.records:
            print(f"Group: {group.name} (ID: {group.id})")

        # Manual pagination using response object
        while response.has_next():
            next_results, error = response.next()
            if error:
                print(f"Error fetching next page: {error}")
                break

            print(f"Next page: {len(next_results)} groups")
            for group in next_results:
                print(f"Group: {group['name']} (ID: {group['id']})")

if __name__ == "__main__":
    main()

Pagination Metadata: The Groups model provides convenient access to pagination metadata: - groups_response.results_total: Total number of records available - groups_response.page_offset: Current page offset - groups_response.page_size: Number of records per page (max 100) - groups_response.next_link: URL for next page (if available) - groups_response.prev_link: URL for previous page (if available) - groups_response.records: Collection of GroupRecord objects

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 GroupsAPI¶

Bases: APIClient

A Client object for the Groups API resource.

add_group(**kwargs)¶

Creates a new Zidentity Group.

Parameters:

**kwargs – Keyword arguments for the group attributes.

Keyword Arguments:

name (str) – The name of the group.
id (str) – Unique identifier for the group.
source (str) – The source type of the group (e.g., ‘SCIM’, ‘MANUAL’, etc.).
is_dynamic_group (bool) – Boolean flag indicating if the group is dynamic.
admin_entitlement_enabled (bool) – Whether the group supports admin entitlements.
service_entitlement_enabled (bool) – Whether the group supports service entitlements.
description (str, optional) – A description of the group.
idp (dict, optional) – Identity provider information associated with the group.

Returns:

A tuple containing the newly added Group, response, and error.

Return type:

tuple

Examples

Add a new Group:

>>> added_group, _, error = client.zidentity.groups.add_group(
...     name="My Test Group",
...     id="group123",
...     source="SCIM",
...     is_dynamic_group=False,
...     admin_entitlement_enabled=True,
...     service_entitlement_enabled=True,
...     description="A test group for demonstration"
... )
>>> if error:
...     print(f"Error adding group: {error}")
...     return
... print(f"Group added successfully: {added_group.as_dict()}")

add_user_to_group(group_id, user_id, **kwargs)¶

Adds a specific user to an existing group using the group ID and the user ID.

Parameters:

group_id (str) – Unique identifier of the group to which the user needs to be added.
user_id (str) – Unique identifier of the user being added to the group.

Returns:

A tuple containing: - An empty dictionary {} on success, - The raw Response object, - Or an Exception if an error occurred. - This returns the client_secret attribute

Return type:

Tuple[dict, Response, Exception]

Examples

Adds a specific user to an existing group:

>>> add_user_to_group, _, error = client.zidentity.groups.add_user_to_group(
... group_id='ia3b1ad9hg66g',
... user_id='ihln05leh07e2'
... )
>>> if error:
...     print(f"Error updating Group: {error}")
...     return
... print(f"Group updated successfully: {add_user_to_group.as_dict()}")

add_users_to_group(group_id, **kwargs)¶

Adds users to an existing group using the unique identifier ID of the group.

Parameters:

group_id (str) – The unique ID for the Group.
**kwargs – Additional parameters including user IDs.

Keyword Arguments:

id (list) – List of user IDs to add to the group. Can be passed as a simple list of strings/integers which will be automatically transformed to the required format.

Returns:

A tuple containing: - An empty dictionary {} on success, - The raw Response object, - Or an Exception if an error occurred. - This returns the client_secret attribute

Return type:

Tuple[dict, Response, Exception]

Examples

Adds users to an existing group with simple ID list:

>>> add_users_to_group, _, error = client.zidentity.groups.add_users_to_group(
...     group_id='ia3b1ad9hg66g',
...     id=['525455', '254545', 'ihln05ktj07ds']
... )
>>> if error:
...     print(f"Error adding users to group: {error}")
...     return
... print(f"Users added successfully: {add_users_to_group.as_dict()}")

delete_group(group_id)¶

Deletes the specified Group.

Parameters:: group_id (str) – The unique identifier of the Group.
Returns:: A tuple containing the response object and error (if any).
Return type:: tuple

Examples

Delete a Group:

>>> _, _, error = client.zidentity.groups.delete_group('73459')
>>> if error:
...     print(f"Error deleting Group: {error}")
...     return
... print(f"Group with ID {'73459' deleted successfully.")

get_group(group_id)¶

Fetches a specific zidentity group by ID.

Parameters:: group_id (int) – Unique identifier of the group to retrieve.
Returns:: A tuple containing Groups instance, Response, error).
Return type:: tuple

Examples

Print a specific Group

>>> fetched_group, _, error = client.zidentity.groups.get_group(
    '1254654')
>>> if error:
...     print(f"Error fetching Group by ID: {error}")
...     return
... print(f"Fetched Group by ID: {fetched_group.as_dict()}")

list_group_users_details(group_id, query_params=None)¶

Retrieves the list of users details for a specific group using the group ID.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.offset] {str}: The starting point for pagination, with the number of records that can be skipped before fetching [query_params.login_name] {str}: Filters results by one or multiple login names. [query_params.limit] {str}: The maximum number of records to return per request. Minimum: 0, Maximum: 1000 [query_params.login_name[like]] {str}: Filters results by group name using a case-insensitive partial match. [query_params.display_name[like]] {str}: Filters results by display name using a case-insensitive partial match. [query_params.primary_email[like]] {str}: Filter results by primary email using a case-insensitive partial match. [query_params.domain_name] {[str]list}: Filter results by primary email using a case-insensitive partial match. [query_params.idp_name] {[str]list}: Filters results by one or more identity provider names.

Returns:

A tuple containing (list of Groups instances, Response, error)

Return type:

tuple

Examples

List users using default settings:

>>> users_list, response, error = zidentity.groups.list_group_users_details():
... if error:
...     print(f"Error listing users: {error}")
...     return
... for user in users_list.records:
...     print(user.as_dict())

List users, limiting to a maximum of 10 items:

list_groups(query_params=None)¶

Retrieves a paginated list of groups with optional query parameters for pagination and filtering by group name or dynamic group status.

See the Zidentity Groups API reference for further detail on optional keyword parameter structures.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.offset] {int}: The starting point for pagination,: with the number of records that can be skipped before fetching results.

[query_params.limit] {str}: The maximum number of records to return per request. Minimum: 0, Maximum: 1000 [query_params.name[like]] {str}: Filters results by group name using a case-insensitive partial match. [query_params.exclude_dynamic_groups] {bool}: Excludes dynamic groups from the results.

Returns:

A tuple containing (list of Groups instances, Response, error)

Return type:

tuple

Examples

List groups using default settings:

>>> group_list, response, error = client.zidentity.groups.list_groups():
... if error:
...     print(f"Error listing groups: {error}")
...     return
... for resource in group_list.records:
...     print(group.as_dict())

List groups, limiting to a maximum of 10 items:

>>> group_list, response, error = client.zidentity.groups.list_groups(query_params={'limit': 10}):
... if error:
...     print(f"Error listing groups: {error}")
...     return
... for resource in group_list.records:
...     print(group.as_dict())

remove_user_from_group(group_id, user_id)¶

Deletes the specified Group.

Parameters:

group_id (str) – Unique identifier of the group to which the user needs to be added.
user_id (str) – Unique identifier of the user being added to the group.

Returns:

A tuple containing: - An empty dictionary {} on success, - The raw Response object, - Or an Exception if an error occurred. - This returns the client_secret attribute

Return type:

Tuple[dict, Response, Exception]

Examples

Delete a Group:

>>> _, _, error = client.zidentity.groups.remove_user_from_group(
...     group_id='ia3b1ad9hg66g',
...     user_id='ihln05ktj07ds'
... )
>>> if error:
...     print(f"Error removing users to group: {error}")
...     return
... print(f"User removed from group successfully.")

replace_users_groups(group_id, **kwargs)¶

Replaces the list of users in a specific group using the group ID. This operation completely replaces all existing users in the group.

Parameters:

group_id (str) – The unique ID for the Group.
**kwargs – Additional parameters including user IDs.

Keyword Arguments:

id (list) – List of user IDs to be replaced in the group. Can be passed as a simple list of strings/integers which will be automatically transformed to the required format.

Returns:

A tuple containing: - An empty dictionary {} on success, - The raw Response object, - Or an Exception if an error occurred. - This returns the client_secret attribute

Return type:

Tuple[dict, Response, Exception]

Examples

Adds users to an existing group with simple ID list:

>>> replace_users, _, error = client.zidentity.groups.replace_users_groups(
...     group_id='ia3b1ad9hg66g',
...     id=['ihln05ttj07ds', 'ihln05tfj07ds', 'ihln05ktj07ds']
... )
>>> if error:
...     print(f"Error replacing users in group: {error}")
...     return
... print(f"Replacement of users successfully: {replace_users.as_dict()}")

update_group(group_id, **kwargs)¶

Updates information for the specified Zidentity Group.

Parameters:: group_id (str) – The unique ID for the Group.
Returns:: A tuple containing the updated Group, response, and error.
Return type:: tuple

Examples

Update an existing Group :

>>> updated_group, _, error = client.zidentity.groups.update_group(
...     group_id='ihlmch6ikg7m1',
...     name=f"ZidentityGroupUpdate_{random.randint(1000, 10000)}",
...     description=f"ZidentityGroup_{random.randint(1000, 10000)}",
...     source='SCIM',
...     admin_entitlement_enabled=True,
...     service_entitlement_enabled=True,
...     dynamic_group=False
... )
>>> if error:
...     print(f"Error updating group: {error}")
...     return
... print(f"Group updated successfully: {updated_group.as_dict()}")