Skip to main content

Getting Started with the Zscaler Python SDK

V2 Python SDK

This guide applies to zscaler-oneapi-sdk-python. For information about zscaler-sdk-python, refer to the GitHub repository.

The Zscaler Python SDK simplifies automation of common administrative tasks by providing Python APIs for Zscaler products. It offers a unified, language-native OneAPI interface that uses a single authenticated session across product APIs, with built-in support for pagination, retries, error handling, and structured logging. The SDK supports Authentication Service, Cloud & Branch Connector (ZTW), Client Connector (ZCC), Zscaler Digital Experience (ZDX), Zscaler Internet Access (ZIA), and Zscaler Private Access (ZPA).

Prerequisites

Before you begin using the Python SDK, ensure that you have:

  • Python 3.10 or later
  • pip (bundled with Python)
  • An Authentication Service-managed tenant with admin access to the products you plan to manage
  • An API client created in Authentication Service. To learn more, see Getting Started with OneAPI and Adding an API Client.

Installation

Install zscaler-oneapi-sdk-python from PyPI in your virtual environment using one of the following options:

Option 1: pip (simplest)​

python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install zscaler-oneapi-sdk-python==1.0.0

Option 2: uv (fastest)​

uv is a modern, high-performance replacement for pip and venv.

# Install uv (one-time)
brew install pipx && pipx install uv     # macOS
# or:  pip install --user pipx && pipx install uv     # Windows / Linux

# Create venv and install the SDK
cd <folder_of_your_choice>
uv venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
uv pip install zscaler-oneapi-sdk-python==1.0.0

Verify the Installation​

python -c "import zssdk; print('Zscaler SDK version:', zssdk.__version__)"

Authentication Requirements

The SDK authenticates via Authentication Service. Create an API client in Authentication Service and note the following values:

  • Client ID: Public identifier for your API client.
  • Client Secret: Confidential secret (for production, use JWT bearer with a private key instead of static secrets).
  • Vanity Domain: Your organization's Authentication Service subdomain (for example, acme if your login URL is https://acme.zslogin.net).

Configure Credentials

Choose one of the following three options to configure your credentials. The SDK resolves them in the following order: constructor args → env vars → ~/.zscaler/config.

# macOS / Linux
export ZSCALER_VANITY_DOMAIN="acme"
export ZSCALER_CLIENT_ID="your_client_id"
export ZSCALER_CLIENT_SECRET="your_client_secret"
REM Windows Command Prompt
set ZSCALER_VANITY_DOMAIN=acme
set ZSCALER_CLIENT_ID=your_client_id
set ZSCALER_CLIENT_SECRET=your_client_secret
# Windows PowerShell
$env:ZSCALER_VANITY_DOMAIN="acme"
$env:ZSCALER_CLIENT_ID="your_client_id"
$env:ZSCALER_CLIENT_SECRET="your_client_secret"

Option 2: Configuration File​

# ~/.zscaler/config
[default]
vanity_domain = acme
client_id = your_client_id
client_secret = your_client_secret
from zssdk import Session
session = Session(profile_name="default")

Option 3: Constructor​

from zssdk import Session
session = Session(
    vanity_domain="acme",
    client_id="your_client_id",
    client_secret="your_client_secret",
)

Make an API Call

  1. Save the following Python code as test_connection.py.

    import zssdk

    session = zssdk.Session()  # picks up ZSCALER_* env vars

    zid = session.zid
    for api_client in zid.api_clients.all().limit(5):
        print(api_client.id, api_client.name)

  2. Run the test_connection.py script from within your virtual environment.

    source .venv/bin/activate     # Windows: .venv\Scripts\activate
    python test_connection.py

You should see a list of up to 5 API clients from your Authentication Service tenant. If you don't, turn on logging as described in the following section and review the log file.

Logging

Enable logging while you explore the SDK using the following code snippet.

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

config = Config(
    logger_config=LoggerConfig(
        enabled=True,
        verbose=True,
        log_to_file=True,
        log_file_path="zssdk.log",
    )
)

session = zssdk.Session(config=config)

Fields containing sensitive information, such as authorization, client secret, and private keys, are auto-redacted. To learn more about full-format logging and redaction, see the Logging guide for complete reference.

Additional References

Use the following links to access SDK references for specific products:

Use the following links to access platform guides that include key concepts and procedural information:

Next Steps

  1. Read the Authentication guide and plan to use JWT bearer authentication rather than static client secrets in production.
  2. Explore the product help pages in the preceding section and implement your first resource using the CRUDL pattern.
  3. For production, configure logging with logging_format="json" for structured logs.

Troubleshooting

The following sections provide troubleshooting steps for common issues you might encounter when working with the SDKs.

Authentication Failure​

  • Verify that your client_id and client_secret are correct and that the API client is active in Authentication Service.
  • Confirm that vanity_domain matches your Authentication Service tenant (subdomain only, not the full URL).
  • If you're testing against the Authentication Service beta environment, pass cloud="beta" to Session(). Omit cloud for production.
  • Ensure that the API client has the required scopes for the product to which you are making API calls.

SSL Certificate Error​

  • Update certificates using the following command: pip install --upgrade certifi.
  • If you're using a corporate proxy, configure Proxy in Config.

Rate Limit Exceeded​

  • The SDK retries 429 responses automatically with exponential backoff and honors Retry-After. If you're still hitting the limit, either slow the caller or catch ThrottledException for application-specific handling. See the Rate Limiting guide.

Getting Help

Zscaler offers the following support channels to help you troubleshoot issues, engage with the community and experts, and request enhancements:

  • Zscaler Community for questions and discussions
  • Zscaler Support for account-specific issues
  • GitHub issues in the SDK repository for bug reports and feature requests

Ready to build? Go to the Authentication guide to finalize your credentials, then choose a product reference from the preceding sections.