zscaler-sdk-python 2.0.0b2

Zscaler SDK for Python

Official Zscaler OneAPI SDK for Python

---

Table of Contents

• Overview
• Why This SDK
• Prerequisites
• Installation
• Building the SDK
• Getting Started
  • Authentication
  • Basic Usage
• Configuration
  • Configuration File
  • Environment Variables
  • Constructor Parameters
  • Configuration Precedence
• API Layers
  • Resource Layer (Recommended)
  • Service Client Layer
• Supported Products
• ZPA: customer_id Requirement
• ZIA and ZTW Context Manager
• Collections and Pagination
• Error Handling
• Rate Limiting and Retry Mechanism
• Logging
• Auto-completion and IntelliSense
• Examples
• Migrating from zscaler-sdk-python
• Contributing
• Need Help?

---

Overview

The Zscaler OneAPI SDK for Python (zscaler-sdk-python) provides a convenient and consistent interface for interacting with Zscaler product APIs through the OneAPI framework.

This SDK is designed exclusively for OneAPI. It uses OAuth2 authentication via Zscaler Identity (Zidentity) and provides a high-level Session object that manages credentials, configuration, and API calls.

This SDK can be used in your server-side code to interact with the Zscaler API platform across multiple products such as:

• ZPA API
• ZIA API
• ZDX API
• ZCC API
• ZIdentity
• ZTW API

Note: This SDK (zscaler-sdk-python) is the next-generation replacement for the previous zscaler-sdk-python package. See Why This SDK and Migrating from zscaler-sdk-python below.

Key Features

• True resource objects with dot notation — Work with resources as Python objects (user.name, cred.fqdn), not raw dictionaries (user["name"]). Attribute access, assignment, and IDE auto-completion work out of the box.
• Active Record pattern — Create, read, update, and delete resources with natural method calls: cred.create(), cred.load(), cred.update(), cred.delete(). No need to call separate service methods and pass IDs around.
• Non-standard operations as first-class methods — Operations beyond CRUDL (e.g., activate(), bulk_delete_assistant(), export_application(), validate_wild_card_domain_name()) are dynamically generated from API metadata and exposed as snake_case methods on the same resource instances — no drop-down to a low-level client required.
• Iterator-based collections with chaining — Paginate effortlessly with .all(), apply server-side filters with .filter(), cap results with .limit(), tune performance with .page_size(), and apply client-side JMESPath queries with .search() — all chainable in a single expression.
• Python exceptions, not error tuples — Errors raise typed exceptions (BadRequestException, NotFoundException) with full context. Use standard try/except instead of unpacking (result, response, error) tuples on every call.
• Automatic snake_case / camelCase conversion — Write idiomatic Python everywhere. The SDK transparently converts to API camelCase on the wire and back.
• One session, all products — A single Session with unified OAuth2 authentication gives you session.zia, session.zpa, session.zcc, session.zid, session.zdx, and session.ztw. No per-product client setup or separate credentials.
• IDE auto-completion and type checking — Ships with PEP 484 .pyi type stubs. VS Code, PyCharm, and other editors provide auto-complete, parameter hints, and docstrings for every resource and method.
• Transparent retry and rate-limit handling — Built-in exponential backoff with Retry-After header support. Rate limits and transient errors are handled automatically — no retry logic needed in your code.
• Metadata-driven architecture — API operations, shapes, pagination, and error mappings are defined in JSON metadata generated from TypeSpec. New endpoints are added via JSON, not Python code.
• Context managers for ZIA/ZTW activation — with session.zia as zia: automatically activates staged configuration changes on exit. No manual activation calls required.

SDK Design and Data Model

This SDK uses a resource-oriented design with the following characteristics:

• Resource objects — Resources (e.g., VpnCredential, UserProfile) are Python objects with attribute access (dot notation), e.g., cred.fqdn, user.login_name.
• Snake_case — Property names use snake_case in Python while the SDK maps to/from API camelCase automatically.
• Native types — Data is represented as native Python types; responses are JSON-serializable.

---

Why This SDK

If you are currently using zscaler-sdk-python, here is why you should switch to zscaler-sdk-python:

Capability	zscaler-sdk-python v1	zscaler-sdk-python v2
Data access	Raw dict — user["name"]	Resource objects — user.name
CRUD pattern	Service methods returning (result, resp, error) tuples	Active Record — resource.create(), .load(), .update(), .delete()
Error handling	Go-style tuples: result, resp, err = ...	Python exceptions: try / except NotFoundException
Pagination	Manual loop with resp.has_next() / resp.next()	Iterator-based: for item in resources.all().limit(100)
Filtering	Manual query params dict	Chainable .filter() + .search() (JMESPath)
Case conversion	Caller manages camelCase ↔ snake_case	Automatic — write snake_case, API receives camelCase
IDE support	No type stubs	PEP 484 .pyi stubs — auto-completion, param hints, docstrings

Side-by-side comparison

Previous SDK — dict access, error tuples, manual pagination:

from zscaler import ZscalerClient

config = {"clientId": "...", "clientSecret": "...", "vanityDomain": "..."}

with ZscalerClient(config) as client:
    # List users — must unpack tuple on every call
    users, resp, err = client.zia.user_management.list_users()
    if err:
        print(f"Error: {err}")
    else:
        for user in users:
            print(user["name"])  # dict access

    # Manual pagination
    while resp.has_next():
        more_users, resp, err = resp.next()
        if err:
            break
        for user in more_users:
            print(user["name"])

This SDK — resource objects, exceptions, iterator collections:

from zssdk import Session

session = Session(vanity_domain="...", client_id="...", client_secret="...")

# Iterate all users — pagination is automatic
for user in session.zia.admin_users.all():
    print(user.name)  # attribute access

# Chain filters, limits, and search in one expression
for user in session.zia.admin_users.filter(search="SDWAN").limit(10):
    print(user.name)

# Errors are exceptions, not return values
from zssdk.zsresource.exceptions import NotFoundException
try:
    role = session.zia.AdminRole(id=99999)
    role.load()
except NotFoundException:
    print("Role not found")

---

Prerequisites

• Python 3.10+
• An administrator account for the Zscaler products you wish to manage
• API credentials created in the Zscaler Identity Admin UI (Client ID and Client Secret)

---

Installation

Install the SDK from PyPI:

pip install zscaler-sdk-python

Or install from source (e.g., for development):

pip install -e /path/to/oneapi-sdk/python

---

Building the SDK

In most cases, you won't need to build the SDK from source. If you want to build it yourself:

1. Clone the repository
2. Navigate to the python directory
3. Run python -m build (requires the build package: pip install build)
4. Install the built package: pip install dist/zssdk_python-*.whl or pip install dist/zssdk_python-*.tar.gz

---

Getting Started

Authentication

The SDK uses OAuth2 via Zscaler Identity (Zidentity). You must have an API Client created in the ZIdentity platform.

OneAPI (API Client Scope)

OneAPI resources are automatically created within the ZIdentity Admin UI based on the RBAC roles applicable to APIs within the various products. For example, in ZIA, navigate to Administration → Role Management and select Add API Role. Once this role has been saved, return to the ZIdentity Admin UI and from the Integration menu select API Resources. Click the View icon to the right of Zscaler APIs and under the ZIA dropdown you will see the newly created role. In the event a newly created role is not seen in the ZIdentity Admin UI, a Sync Now button is provided in the API Resources menu which initiates an on-demand sync of newly created roles.

Required parameters:

• vanity_domain — Your organization's vanity domain (e.g., acme). Use only the vanity part; full domains like acme.zslogin.net are not allowed. Refers to the domain used by your organization: https://<vanity_domain>.zslogin.net/oauth2/v1/token.
• client_id — Your Zidentity API Client ID
• client_secret — Your API Client secret
• cloud — (Optional) Omit for production. Use only when authenticating to a non-production environment such as alpha or beta (test-based tenants).

Caution: Do not hard-code credentials. Use environment variables or the configuration file instead.

Basic Usage

Create a Session and access services as attributes. The SDK dynamically provides service resources when you access them.

import os
from zssdk import Session

# Create a session using environment variables (omit cloud for production)
session = Session(
    cloud=os.getenv("ZSCALER_CLOUD"),  # Optional: only for alpha/beta
    vanity_domain=os.getenv("ZSCALER_VANITY_DOMAIN"),
    client_id=os.getenv("ZSCALER_CLIENT_ID"),
    client_secret=os.getenv("ZSCALER_CLIENT_SECRET"),
)

# Access ZIA and list VPN credentials
zia = session.zia
for cred in zia.vpn_credentials.all().limit(10):
    print(cred.fqdn, cred.id)

# Access ZID and list user profiles
zid = session.zid
for user in zid.user_profiles.all().limit(5):
    print(user.login_name, user.display_name)

Using the default session: You can call setup_default_session(**kwargs) once to configure a shared session, then use get_default_session() anywhere. The zssdk.client() helper returns a low-level client from the default session.

---

Configuration

Configuration File

Create a configuration file at ~/.zscaler/config. The file uses INI format with named profiles (you can also use config.ini and pass config_file="/path/to/config.ini" to Session):

[default]
vanity_domain = your_vanity_domain
client_id = your_client_id
client_secret = your_client_secret

[beta]
cloud = beta
vanity_domain = your_vanity_domain
client_id = your_beta_client_id
client_secret = your_beta_client_secret

Note: Profile names (e.g., [default], [beta]) are arbitrary labels you choose. The cloud key within a profile is what selects the non-production Zscaler environment. Omit cloud entirely for production.

Use a profile by name:

session = Session(profile_name="beta")

For multi-product setups with different clouds, define separate profiles and pass profile_name when creating the session for each product.

Environment Variables

Credential and cloud settings (prefix ZSCALER_):

Variable	Description
ZSCALER_CLOUD	Non-production environment only (e.g., alpha, beta); omit for production
ZSCALER_VANITY_DOMAIN	Your organization's vanity domain
ZSCALER_CLIENT_ID	OAuth2 Client ID
ZSCALER_CLIENT_SECRET	OAuth2 Client Secret
ZSCALER_PRIVATE_KEY	Private key string (for JWT Bearer auth)
ZSCALER_CERT_FILE_PATH	Path to private key file (for certificate-based auth)
ZSCALER_PROFILE	Default profile name (default: default)

SDK-level settings (prefix ZSSDK_), defined in zssdk.zscore.configprovider:

Variable	Description
ZSSDK_API_VERSION	API version (default: v1)
ZSSDK_USE_FIPS_ENDPOINT	Use FIPS endpoints (true / false)
ZSSDK_LOG_ENABLED	Enable SDK logging (true / false)
ZSSDK_LOG_VERBOSE	Verbose logging (true / false)
ZSSDK_LOG_TO_FILE	Log to file (true / false)
ZSSDK_LOG_FILE_PATH	Log file path (default: zssdk.log)
ZSSDK_LOG_FORMAT	Log format: basic, json, or custom (see Logging)

Constructor Parameters

You can pass credentials and settings directly to Session:

session = Session(
    vanity_domain="acme",
    client_id="your_client_id",
    client_secret="your_client_secret",
    profile_name="beta",        # Use config file profile
    config_file="/path/to/config",  # Custom config path
)

For JWT Bearer (client assertion) authentication:

session = Session(
    vanity_domain="acme",
    client_id="your_client_id",
    cert_file_path="/path/to/private_key.pem",  # Or private_key="<key string>"
)

Configuration Precedence

Configuration is resolved in the following order (highest to lowest):

1. Constructor arguments
2. Instance variables set via session.set_config_variable()
3. Environment variables
4. Configuration file (profile)
5. Default values

User-Agent and Custom Headers

The SDK sends a User-Agent header with each request in the format: oneapi-sdk/<version> python/<py_version> <os>/<os_version>. You can append custom text via the Config object:

from zssdk.zscore.config import Config

config = Config(user_agent_extra="my-app/1.0")
session = Session(config=config, profile_name="beta")
# User-Agent will be: oneapi-sdk/<version> python/<version> <os>/<release> my-app/1.0

---

API Layers

The SDK exposes two ways to interact with Zscaler APIs.

Resource Layer (Recommended)

The resource layer provides a Pythonic, object-oriented interface. Access services as session attributes and work with resources as objects.

Creating and managing a resource:

import zssdk

session = zssdk.Session(profile_name="default")
zia = session.zia

# Create a new VPN credential
cred = zia.VpnCredential()
cred.type = "UFQDN"
cred.fqdn = "[e-mail]"
cred.pre_shared_key = "somekey"
cred.create()
print(f"Created credential with ID: {cred.id}")

# Load an existing resource by ID
loaded = zia.VpnCredential(id=cred.id)
loaded.load()

# Update
loaded.pre_shared_key = "newkey"
loaded.update()

# Delete
cred.delete()

Working with collections:

# List all (iterates over paginated results)
for item in zia.vpn_credentials.all():
    print(item.fqdn)

# Apply server-side filters
for item in zia.vpn_credentials.all().filter(type="UFQDN"):
    print(item.fqdn)

# Limit results
for item in zia.vpn_credentials.all().limit(20):
    print(item.fqdn)

# Control page size for performance tuning
for item in zia.vpn_credentials.all().page_size(50).limit(100):
    print(item.fqdn)

# Client-side filtering with JMESPath (see Collections and Pagination for more examples)
for item in zia.vpn_credentials.all().search("[?type=='UFQDN']"):
    print(item.fqdn)

# Iterate by page
for page in zia.vpn_credentials.all().pages():
    for item in page:
        print(item.fqdn)

ZID (Zscaler Identity) example:

zid = session.zid

# Create user profile
user = zid.UserProfile()
user.login_name = "[e-mail]"
user.display_name = "John Doe"
user.primary_email = "[e-mail]"
user.status = True
user.create()

# List groups
for group in zid.groups.all().limit(10):
    print(group.name)

Service Client Layer

For lower-level access, you can obtain a raw service client via session.client("zia"). This returns a low-level client whose methods map directly to API operations. For typical usage, prefer the resource layer above. Use session.get_available_services() to list available service names (zia, zid, zcc, zpa, zdx, ztw) and session.get_available_resources() for resource-style service names.

---

Supported Products

Product	Service Name	Description
Zscaler Internet Access	zia	ZIA administration and policy management
Zscaler Identity	zid	User, group, and API client management
Zscaler Client Connector	zcc	Client Connector administration
Zscaler Private Access	zpa	ZPA configuration and policies
Zscaler Digital Experience	zdx	ZDX monitoring and analytics
Zscaler Cloud & Branch Connector	ztw	Cloud & Branch Connector management

---

ZPA: customer_id Requirement

When interacting with Zscaler Private Access (ZPA) endpoints, you must provide customer_id in addition to the standard authentication parameters. The customer_id is the ZPA tenant ID, found under Configuration & Control → Public API → API Keys in the ZPA Admin Portal.

For ZPA resources, pass customer_id as a parameter to each operation. Every ZPA API call includes customer_id in the request path (e.g., /customers/{customerId}/...), so you must supply it when creating, updating, or querying ZPA resources.

microtenant_id is optional and only required when using ZPA with Microtenant; pass 0 for the default microtenant.

---

ZIA and ZTW Context Manager

The SDK provides a context manager pattern for ZIA and ZTW that automatically activates configuration changes when exiting the block.

How It Works

When you use the with statement with session.zia or session.ztw:

1. Entry — The service resource is returned; you make configuration changes within the block.
2. Exit — When exiting the context (successfully or via exception), the SDK runs a finalize workflow that activates staged changes.

Activation Process

• ZIA — The finalize workflow calls the activation status endpoint. If the status is PENDING, it deauthenticates the session, which triggers activation of all staged configuration changes.
• ZTW — The finalize workflow fetches the status; if PENDING, it explicitly calls the Activate endpoint.

Example

import zssdk

session = zssdk.Session(profile_name="default")

# ZIA: context manager activates changes on exit
with session.zia as zia:
    role = zia.AdminRole()
    role.name = "New API Role"
    role.description = "Role created via API"
    role.create()
# All staged ZIA changes are activated here

# ZTW: context manager activates changes on exit
with session.ztw as ztw:
    group = ztw.IpDestinationGroup()
    group.name = "New IP Group"
    group.description = "IP group via API"
    group.create()
# All staged ZTW changes are activated here

Benefits

• Automatic activation — No need to call activation endpoints manually.
• Deterministic behavior — Exiting the context always triggers the activation workflow.
• Error handling — Even if an exception occurs, the context manager runs the finalize logic on normal exit (exceptions are not suppressed).

---

Collections and Pagination

Collections support the following methods:

Method	Description
.all()	Returns an iterable over all resources (handles pagination)
.filter(**kwargs)	Applies server-side filters (snake_case or camelCase)
.limit(n)	Stops after yielding n resources
.page_size(n)	Sets the number of resources fetched per API request
.search(expr)	Client-side JMESPath filtering on each page
.pages()	Yields pages (lists) of resources instead of individual items

Example with combined options:

# Server-side filter, custom page size, limit total results
for cred in (
    zia.vpn_credentials.all()
    .filter(type="UFQDN")
    .page_size(25)
    .limit(100)
):
    print(cred.fqdn)

Client-side filtering with JMESPath

The .search(expr) method applies a JMESPath expression on each page of results. Use it when you need filtering that the API does not support server-side. The expression is applied to the items array, so you write it relative to each item.

# Exact match on a field
for user in zia.admin_users.search("[?name == 'SDWAN-SilverPeak']"):
    print(user.name)

# Multiple values with OR
for user in zia.admin_users.search("[?name == 'SDWAN-SilverPeak' || name == 'SDWAN-VeloCloud']"):
    print(user.name)

# Substring match using contains()
for user in zia.admin_users.search("[?contains(name, 'SilverPeak')]"):
    print(user.name)

# Chain with server-side filter (filter first to reduce data, then search)
for user in zia.admin_users.filter(search="SDWAN").search("[?contains(name, 'SilverPeak')]"):
    print(user.name)

# Chain with limit and page_size
for user in zia.admin_users.search("[?name == 'SDWAN-SilverPeak']").limit(10).page_size(50):
    print(user.name)

---

Error Handling

The SDK raises structured exceptions:

Exception	Base	When it occurs
OneApiError	—	Base SDK error
ZsResourceError	OneApiError	Resource-level errors; includes resource_name, action_name
BadRequestException	ZsResourceError	API returns 400 Bad Request
NotFoundException	ZsResourceError	API returns 404 Not Found

Additional resource-specific exceptions (e.g., ConflictException) may be defined in zssdk.zsresource.exceptions.

Example:

from zssdk.zscore import OneApiError
from zssdk.zsresource import ZsResourceError
from zssdk.zsresource.exceptions import BadRequestException

try:
    cred = zia.VpnCredential()
    cred.fqdn = "invalid"
    cred.create()
except BadRequestException as e:
    print(f"Bad request: {e}")
except ZsResourceError as e:
    print(f"Resource error: {e.resource_name} / {e.action_name}: {e}")
except OneApiError as e:
    print(f"SDK error: {e}")

---

Rate Limiting and Retry Mechanism

Each Zscaler product has its own rate limiting criteria. Product-specific limits and quotas are documented in the Zscaler Automation Hub Rate Limiting Guide.

Built-in Retry Mechanism

The SDK includes a built-in retry mechanism (configured in zssdk.zscore.data._retry) that handles rate limiting and transient failures automatically. When a retryable response or connection error occurs, the SDK:

1. Checks for rate limit headers — If present, waits the specified time before retrying.
2. Falls back to exponential backoff — If no header is present, uses exponential backoff (base 0.3s, growth factor 2).
3. Caps wait time — Maximum wait is 300 seconds per retry.
4. Limits attempts — Retries up to 3 times (max_attempts) before raising the final exception.

The retry logic is applied per request across all supported products (ZIA, ZID, ZCC, ZPA, ZDX, ZTW).

HTTP Status Codes That Trigger Retries

The SDK retries requests when it receives one of the following responses:

Status Code	Meaning	Policy Name
429	Too Many Requests	TooManyRequests, Throttling
500	Internal Server Error	ServerError (with TransientFailure)
502	Bad Gateway	BadGateway
503	Service Unavailable	ServiceUnavailable
504	Gateway Timeout	GatewayTimeout

Connection errors (e.g., ConnectionError, ReadTimeoutError) also trigger retries.

Retry-After and Rate Limit Headers

When rate limiting is enabled (default), the SDK uses response headers to determine how long to wait before retrying. Headers are checked in this order:

1. Retry-After or retry-after — Standard HTTP headers. Supports values like 9 (seconds) or 9s.
2. x-ratelimit-reset, X-RateLimit-Reset, RateLimit-Reset, X-Rate-Limit-Retry-After-Seconds — Product-specific headers indicating seconds until the rate limit resets.

If no rate limit header is present, the SDK falls back to exponential backoff (base 0.3s, growth factor 2).

---

Logging

SDK logging is controlled by environment variables (see Environment Variables) or a LoggerConfig object.

Log format (ZSSDK_LOG_FORMAT)

The logging_format setting supports three values:

Format	Description
basic	Human-readable lines: %(asctime)s - %(name)s - %(module)s - %(levelname)s - %(message)s. Default format.
json	Structured JSON output, one record per line, suitable for log aggregators (e.g., Grafana Loki).
custom	Use your own logging.Formatter instance. Only available programmatically via LoggerConfig; requires passing custom_formatter and cannot be set via environment variables.

Environment variables example:

export ZSSDK_LOG_ENABLED=true
export ZSSDK_LOG_VERBOSE=false
export ZSSDK_LOG_TO_FILE=false
export ZSSDK_LOG_FILE_PATH=zssdk.log
export ZSSDK_LOG_FORMAT=basic

Programmatic configuration:

from zssdk.zscore.config import Config, LoggerConfig

config = Config(
    logger_config=LoggerConfig(
        enabled=True,
        verbose=False,
        logging_format="json",
        log_to_file=True,
        log_file_path="/var/log/zssdk.log",
    )
)
session = Session(config=config, profile_name="default")

Custom format (programmatic only):

import logging
from zssdk.zscore.config import Config, LoggerConfig

custom_formatter = logging.Formatter("%(levelname)s | %(message)s")
config = Config(
    logger_config=LoggerConfig(
        enabled=True,
        logging_format="custom",
        custom_formatter=custom_formatter,
    )
)
session = Session(config=config, profile_name="default")

Sensitive fields (tokens, secrets, passwords) are redacted in log output.

---

Auto-completion and IntelliSense

The SDK ships with PEP 484 type stub files (.pyi) that enable rich IDE support. Compatible editors (e.g., VS Code with Pylance, PyCharm) automatically use these stubs for:

• Auto-completion — As you type session.zia. or cred., the IDE suggests available resources, methods, and properties.
• Parameter hints — Method signatures and parameter names appear in tooltips.
• Docstrings — Resource and method documentation is shown in hover tooltips.
• Type checking — Static type checkers (e.g., Pyright, mypy) can validate your code.

What You Get

Location	Stub file(s)	Purpose
Session / services	session.pyi	session.zia, session.zid, etc.
ZIA resources	zia_resources.pyi	VpnCredential, AdminUser, collections
ZID resources	zid_resources.pyi	UserProfile, Group, ApiClient
ZPA, ZCC, ZDX, ZTW	*_resources.pyi	Product-specific resources and methods
Low-level clients	*_client.pyi	Service client method signatures

Setup

No additional setup is required. The stubs are part of the installed package and are picked up automatically by IDEs that support PEP 484. Ensure your IDE's Python interpreter points to the environment where zscaler-sdk-python is installed.

Example

When you type session.zia. in VS Code or PyCharm, you will see completions for resources such as VpnCredential, AdminUser, vpn_credentials, and admin_users. Selecting a resource shows its available properties and methods (e.g., create(), load(), update(), delete()).

---

Examples

The repository includes runnable CLI scripts and inline examples under examples/, organized by product. Prerequisites and configuration are covered in the Configuration section above.

All CLI scripts are self-documenting. Run any script with no arguments for a usage hint, or --help for the full reference:

python examples/zid/user_management/user_management.py --help
python examples/zia/vpn_credentials_management/vpn_credentials_management.py --help

---

Migrating from zscaler-sdk-python

If you are coming from the previous zscaler-sdk-python package, here is what changes.

Installation

# Remove the old package
pip uninstall zscaler-sdk-python

# Install the new package
pip install zscaler-sdk-python

The import name changes from zscaler to zssdk.

Authentication

Before:

from zscaler import ZscalerClient

config = {
    "clientId": "...",
    "clientSecret": "...",
    "vanityDomain": "...",
    "cloud": "beta",
}
client = ZscalerClient(config)

After:

from zssdk import Session

session = Session(
    client_id="...",
    client_secret="...",
    vanity_domain="...",
    cloud="beta",
)

Key differences:

• Constructor uses Python keyword arguments (snake_case) instead of a config dictionary (camelCase).
• Configuration can also come from ~/.zscaler/config (INI format) or environment variables. See Configuration.

Working with resources

Before — dict access, error tuples:

with ZscalerClient(config) as client:
    role, resp, err = client.zia.admin_roles.get_role(role_id="12345")
    if err:
        print(f"Error: {err}")
    else:
        print(role["name"])

After — resource objects, exceptions:

from zssdk.zsresource.exceptions import NotFoundException

try:
    role = session.zia.AdminRole(id=12345)
    role.load()
    print(role.name)
except NotFoundException:
    print("Role not found")

Pagination

Before — manual loop:

groups, resp, err = client.zia.user_management.list_groups()
while resp.has_next():
    more, resp, err = resp.next()
    if err:
        break
    groups.extend(more)

After — iterator with chaining:

# All groups, paginated automatically
for group in session.zia.admin_roles.all():
    print(group.name)

# With server-side filter and limit
for group in session.zia.admin_roles.filter(search="API").limit(50):
    print(group.name)

Configuration

Before — YAML file at ~/.zscaler/zscaler.yaml:

zscaler:
  client:
    clientId: "..."
    clientSecret: "..."
    vanityDomain: "..."

After — INI file at ~/.zscaler/config:

[default]
vanity_domain = ...
client_id = ...
client_secret = ...

Quick reference

What	zscaler-sdk-python v1	zscaler-sdk-python v2
Import	from zscaler import ZscalerClient	from zssdk import Session
Access field	user["name"]	user.name
Create resource	client.zia.admin_roles.add_role(name="X")	role = session.zia.AdminRole(); role.name = "X"; role.create()
Delete resource	client.zia.admin_roles.delete_role(role_id="123")	role = session.zia.AdminRole(id=123); role.delete()
Handle error	result, resp, err = ...; if err: ...	try: ... except NotFoundException: ...
Paginate	while resp.has_next(): resp.next()	for item in collection.all():
Filter	query_params={"search": "X"}	.filter(search="X") or .search("[?name=='X']")
Config file	~/.zscaler/zscaler.yaml	~/.zscaler/config (INI)

---

Contributing

Contributions are welcome. Please follow the project's coding standards and submit pull requests via the repository's normal workflow.

---

Need Help?

• Zscaler Community
• OneAPI Documentation
• Zscaler Identity API
• ZIA API
• Automation Docs