Session Management

The zssdk.Session object is the SDK's main entry point. It holds credentials, a Config object, a connection pool, and a cache of per-service clients. A single Session authenticates against every Zscaler product.

SDK Session vs. Product Session

The term "session" is used in several different ways. In this SDK, it maps to three distinct concepts:

Concept	Where it lives	Lifetime	Who manages it
`zssdk.Session` (SDK session)	In your process	For as long as you keep the Python object alive	You
Authentication Service OAuth token	Returned by `{vanity_domain}.zslogin.net`	Up to 24 hours, auto-refreshed 5 minutes before expiry	The SDK (automatically)
Backend product session	Inside each product (ZDX, ZIA, ZPA, etc.)	Product-specific. For example, ZIA keeps a server-side session that might expire on the order of minutes; other products vary.	The product's control plane

Key points:

The SDK session is a client-side object that shares configuration, credentials, and HTTP connections across API calls. It does not model or track anything on the server.
The Authentication Service token lifetime (up to 24 hours) is decoupled from backend product sessions. A valid token does not guarantee that a backend product session is still valid.
The backend product sessions (especially ZIA's short-lived session) are owned by the product and are not surfaced through the SDK. You don't need to poll, extend, or refresh them. If the product drops the session, your next call establishes a fresh one.

The SDK is not expected to mirror or report on product-side session timeouts. Every resource call must be treated as idempotent, standard exceptions must be handled for any transient failures that arise from the product-side session lifecycle. To learn more, see Error Handling.

Creating a Session

Create a Session object that holds your credentials and shared configuration for all service clients.

import zssdk
session = zssdk.Session(
    vanity_domain="acme",
    client_id="your-client-id",
    client_secret="your-client-secret",
)

For production environment, prefer a named profile in ~/.zscaler/config:

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

For a full list of credential options (environment variables, JWT bearer, and custom token providers), see Authentication. For the full precedence chain, see Configuration.

Session Parameters

Parameter	Type	Description
`vanity_domain`	str	Required. Your Authentication Service tenant subdomain (e.g., `acme`).
`client_id`	str	OAuth 2.0 client ID from Authentication Service
`client_secret`	str	OAuth 2.0 client secret. Use `cert_file_path` or `private_key` instead for JWT bearer for stronger security.
`cloud`	str \| None	Optional. The only valid explicit value is `"beta"` (Authentication Service beta environment, `zsloginbeta.net`). Omit for production. Legacy cloud names (`zscalerone.net`, `zscalertwo.net`, etc.) are not supported.
`profile_name`	str	Profile name to load from `~/.zscaler/config` (or a file passed via `config_file`)
`config_file`	str	Override the default `~/.zscaler/config` path
`config`	`Config`	Advanced transport, logging, or FIPS configuration, described in the following section.
`cert_file_path`	str	Path to a PEM-encoded private key (JWT bearer auth)
`private_key`	str	Inline PEM private key string (JWT bearer auth)
`token_provider`	`TokenProvider`	Custom token provider for external identity systems

Accessing Services

Every product is exposed as a lazy attribute on the session — that is, created on first access and cached thereafter.

zia = session.zia     # ServiceResource for ZIA
zid = session.zid     # ServiceResource for Authentication Service
zpa = session.zpa
zdx = session.zdx
zcc = session.zcc
ztw = session.ztw

# List the service names the session knows about
print(session.get_available_services())

Advanced `Config`

Bundle transport, proxy, FIPS, and logging settings into a Config object and pass it to the session:

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

config = Config(
    http_connection=HttpConnection(
        connect_timeout=30.0,
        read_timeout=60.0,
        max_connections=200,
    ),
    proxy=Proxy(host="proxy.company.com", port=8080),
    use_fips_endpoint=True,
    logger_config=LoggerConfig(
        enabled=True,
        logging_format="json",
        log_to_file=True,
        log_file_path="/var/log/zssdk.log",
    ),
)

session = zssdk.Session(
    vanity_domain="acme",
    client_id="your-client-id",
    client_secret="your-client-secret",
    config=config,
)

For proxy, timeout, and FIPS details, see Authentication. For the full LoggerConfig reference, see Logging.

Multiple Sessions

Create additional sessions to work with multiple tenants or environments in the same process:

tenant_a = zssdk.Session(profile_name="tenant-a")
tenant_b = zssdk.Session(profile_name="tenant-b")

for role in tenant_a.zia.admin_roles.all():
    print("tenant-a:", role.name)

for role in tenant_b.zia.admin_roles.all():
    print("tenant-b:", role.name)

Each Session has independent credentials, a separate connection pool, and its own token cache.

Authentication — OAuth 2.0, JWT bearer, custom token providers
Configuration — Profile format, env vars, precedence
Logging — Structured log output and automatic redaction
Error Handling — Exception hierarchy for failed operations