Configuration

The SDK resolves credentials and behavior settings from four sources, in order of precedence:

1. Constructor arguments
2. Instance variables
3. Environment variables
4. A config file at ~/.zscaler/config

This article describes each source, how they interact, and the precedence rules used among them.

---

Quick Start Using a Profile

The simplest production pattern is to use a named profile in ~/.zscaler/config:

# ~/.zscaler/config
[default]
vanity_domain = acme
client_id = your_client_id
client_secret = your_client_secret

[beta]
cloud = beta
vanity_domain = acme-beta
client_id = beta_client_id
client_secret = beta_client_secret

import zssdk
session = zssdk.Session(profile_name="beta")

The config file uses INI format. Each [section] represents a named profile. If you do not set profile_name, the SDK uses the [default] profile.

You can also load the config from a custom path:

session = zssdk.Session(profile_name="beta", config_file="/etc/zscaler/config.ini")

Configuration Sources

1. Constructor Arguments

Constructor arguments are the most explicit source: values passed directly to Session() override all other sources.

session = zssdk.Session(
    vanity_domain="acme",
    client_id="...",
    client_secret="...",
    cloud="beta",        # omit for production
)

2. Environment Variables

Credentials use the ZSCALER_* prefix; SDK behavior settings use ZSSDK_*.

Credential and Cloud Settings (ZSCALER_*):

Variable	Description
ZSCALER_CLOUD	Optional. The only valid explicit value is beta (Authentication Service beta environment). Omit for production. Legacy cloud names (e.g., zscalerone.net) are not supported.
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 (JWT bearer authentication)
ZSCALER_CERT_FILE_PATH	Path to a private-key PEM file (certification-based authentication)
ZSCALER_PROFILE	Default profile name, which is default.

SDK Behavior Settings (ZSSDK_*):

Variable	Description
ZSSDK_API_VERSION	API version (default: v1)
ZSSDK_USE_FIPS_ENDPOINT	Route traffic through FIPS endpoints (true or false)

3. Config file (~/.zscaler/config)

The config file uses INI format. Each profile is defined as a section:

[default]
vanity_domain = acme
client_id = prod_id
client_secret = prod_secret

[beta]
cloud = beta
vanity_domain = acme
client_id = beta_id
client_secret = beta_secret

Only cloud = beta is a valid explicit cloud value (it targets the Authentication Service beta environment). For production, omit cloud entirely.

You can select a profile with the profile_name parameter:

prod = zssdk.Session(profile_name="default")
beta = zssdk.Session(profile_name="beta")

# Use each session independently
for role in prod.zia.admin_roles.all():
    print("prod:", role.name)
for role in beta.zia.admin_roles.all():
    print("beta:", role.name)

4. Instance variables (runtime override)

You can override any resolved configuration value at runtime by using instance variables:

session = zssdk.Session(profile_name="default")
# Override any resolved config value at runtime
session.set_config_variable("cloud", "beta")

Precedence

Configuration values are resolved in order of precedence, from highest to lowest, as follows:

1. Constructor arguments passed to Session()
2. Instance variables set via session.set_config_variable()
3. Environment variables (ZSCALER_* and ZSSDK_*)
4. Config file profiles (~/.zscaler/config)
5. Built-in defaults

Related

• Authentication: OAuth2, JWT, and custom token providers
• Session management: Session lifecycle and available services
• Logging: How to enable structured logging