ZTB (Zero Trust Branch) Authentication and Usage¶

ZTB authenticates via API key. The SDK calls POST /api/v3/api-key-auth/login with {"api_key": "..."} and receives a delegate_token used as Authorization: Bearer <token> for all subsequent requests.

Environment Variables¶

Variable	Req.	Description
`ZTB_API_KEY`	Yes*	ZTB API key created in the ZTB UI
`ZTB_CLOUD`	Yes**	Cloud subdomain (e.g. `zscalerbd-api`). Base URL: `https://{cloud}.goairgap.com`
`ZTB_OVERRIDE_URL`	No	Full base URL override. If set, `cloud` is not required.
`ZSCALER_PARTNER_ID`	No	Partner ID for `x-partner-id` header

* Or pass api_key in config. ** Or ZTB_OVERRIDE_URL; at least one of cloud or override_url is required.

Configuration Options¶

Option	Default	Description
`api_key`	required	ZTB API key from the ZTB console
`cloud`	required*	Cloud subdomain (e.g. `zscalerbd-api`)
`override_url`	`None`	Full base URL override. Include protocol (`https://`).
`partner_id`	`None`	Partner ID for `x-partner-id` header
`timeout`	`240`	Request timeout in seconds
`max_retries`	`5`	Max retry attempts for 429/5xx/network errors

* Required if override_url is not set.

Important Notes¶

ZTB is available only via the Legacy client (LegacyZTBClient). OneAPI/OAuth2 is not supported for ZTB.
On 401 Unauthorized, the client automatically re-authenticates and retries once.
On 429 (rate limit) or 5xx (502/503/504), the SDK retries with exponential backoff.
Request bodies remain in snake_case; query parameters are converted to camelCase by the SDK.

Available Resources¶

Resources are accessed via client.ztb.<resource>:

alarms — Alarms API
api_keys — API key auth
app_connector_config — App connector configuration
devices — Active devices, device tags, OS list, device details, DHCP history, filter values
groups_router — Groups router
logs — Logs and visibility charts
policy_comments — Policy comments
ransomware_kill — Ransomware kill
site — Site management
site2site_vpn — Site-to-site VPN (Cloud Gateway)
template_router — Template router

Example¶

from zscaler.oneapi_client import LegacyZTBClient

config = {
    "api_key": "{yourZTBAPIKey}",
    "cloud": "zscalerbd-api",
    "logging": {"enabled": False, "verbose": False},
}

def main():
    with LegacyZTBClient(config) as client:
        alarms, response, error = client.ztb.alarms.list_alarms()
        if error:
            print(f"Error: {error}")
            return

        devices, _, err = client.ztb.devices.list_active_devices(
            query_params={"page": 1, "limit": 25}
        )
        if not err:
            for d in devices:
                print(d.hostname)

if __name__ == "__main__":
    main()