Skip to main content

​
About Zscaler

Zscaler is a zero trust security platform for internet access, private access, digital experience, and cloud security. Serval connects through Zscaler OneAPI using a ZIdentity API client, then runs workflows against your tenant on demand. Authentication: OAuth 2.0 client credentials from ZIdentity. Serval stores your Client ID, Client Secret, vanity domain, and cloud setting, then exchanges them for short-lived access tokens during workflow runs. Data sync: on demand only. Serval does not run a background sync for Zscaler; workflows call OneAPI live.

​
What the Zscaler integration enables

​
Get your credentials

You need a ZIdentity API client with access to the Zscaler APIs your workflows will call.
1

Create or choose a ZIdentity API client

In ZIdentity, create an API client for Serval or choose an existing automation client.
2

Grant API resource access

Add the ZIA, ZPA, Client Connector (ZCC), and Digital Experience (ZDX) API resources required for the workflows you plan to run. Start with read-only access for inventory workflows. Device OTP retrieval needs ZCC access that can return OTP secrets. ZDX workflows need a ZDX Advanced or Advanced Plus subscription.
3

Copy the Client ID and Client Secret

Copy the Client ID and Client Secret. Store the Client Secret before leaving the creation screen.
4

Record your vanity domain

Record the vanity domain prefix from your token URL. For https://acme.zslogin.net/oauth2/v1/token, enter acme in Serval.
5

Record your ZPA customer ID

If you plan to run ZPA workflows, copy the ZPA customer ID from the ZPA Admin Portal.

​
Connect in Serval

1

Open the Zscaler connect form

In Serval, open the Zscaler integration and start a new connection.
2

Enter the instance name

Use a name like Production or Corporate.
3

Enter the vanity domain

Enter only the vanity prefix, such as acme.
4

Enter the cloud

Leave this blank for production. Enter values like beta or alpha only when your Zscaler tenant uses that OneAPI cloud. GOV and GOVUS tenants are not supported by Zscaler OneAPI.
5

Enter the client credentials

Paste the ZIdentity Client ID and Client Secret.
6

Optionally enter ZPA fields

Enter the ZPA customer ID and microtenant ID if you want them stored on the connection. ZPA workflows also ask for the customer ID explicitly.

​
Verifying the connection

Serval runs five health checks against your Zscaler connection. The first one tells you which stage failed, so read its message before changing anything. Validate Zscaler OneAPI Connection - exchanges the stored ZIdentity client credentials for an access token, then reads ZIA status.
  • Pass: “Successfully connected to Zscaler OneAPI.”
  • Fail, token exchange: Serval couldn’t obtain an access token, so OneAPI was never called. Verify the vanity domain, Client ID, and Client Secret. The message includes the ZIdentity error code, such as invalid_client, when ZIdentity returns one.
  • Fail, host unreachable: Serval couldn’t connect to the OneAPI host. Check the connection’s cloud value.
  • Fail, ZIA rejected the token (HTTP 401): the token was issued, but the API client isn’t granted the ZIA resource in ZIdentity, or the connection’s cloud value doesn’t match the tenant. This is expected on a connection that only serves ZDX, ZPA, or Client Connector workflows.
List Zscaler Admin Users, List Zscaler Admin Roles, and List Zscaler Locations - confirm the API client can read ZIA administrators, roles, and locations. On an API client without the ZIA resource, all three fail with the same “not granted the ZIA resource” message as the first check. List ZDX Departments - lists the configured ZDX departments, which confirms the API client is granted the Digital Experience (ZDX) resource and the tenant has a ZDX Advanced or Advanced Plus subscription. On a connection that isn’t used for ZDX, this check fails and says so. Switch it off for that connection so the connection is no longer flagged as unhealthy. ZPA and Client Connector have no dedicated health check. Run one of their workflows to confirm the API client’s resource grants.
On an API client granted only the ZDX resource, List ZDX Departments passes while the four ZIA checks fail with the “not granted the ZIA resource” message. The connection works for ZDX workflows. Grant the ZIA resource only if you plan to run ZIA workflows.

​
Client Connector device OTPs

To retrieve a ZIA disable OTP or related Client Connector OTP for a user device:
  1. List enrolled devices, optionally filtered by username, and copy the device udid.
  2. Request OTPs for that udid. The response can include ziaDisableOtp, exitOtp, logoutOtp, uninstallOtp, and related values.
Device OTP retrieval requires installer approval because the returned values can disable Client Connector protections.

​
Digital Experience (ZDX)

ZDX workflows run against the same OneAPI connection once the ZIdentity API client has the ZDX resource. Start with Find ZDX Devices for User, which resolves a requester’s active devices by email, then pass a returned device ID to the device detail and health metric workflows. Most ZDX endpoints cover the last 2 hours of data.
If your tenant still holds a legacy ZDX API key, the separate Zscaler ZDX (Legacy API Key) integration continues to work. Zscaler does not offer legacy ZDX keys on tenants that never had one, so new ZDX connections should use this integration.

​
Audit log reports

Serval can create a ZIA administrator audit log report for an epoch timestamp range, check the report generation status, and download the latest generated report. Creating a new ZIA audit log report overwrites the previous generated report in Zscaler.
These workflows use Zscaler’s audit report API. They do not replace NSS, LSS, or Cloud NSS streaming for web, firewall, DNS, or ZPA activity logs.
ZPA workflows require a ZPA customer ID. The ID is part of each ZPA request path and is not interchangeable with the Serval integration ID or ZIA organization IDs.