Zscaler User Management API Guide

Auth method: API Key + Session Cookie (ZIA proprietary auth). Caller POSTs credentials and API key to /authenticatedSession to obtain a JSESSIONID cookie used on subsequent requests.

Setup steps

1. In the ZIA Admin Portal, navigate to Administration > API Key Management and generate an API key (obfuscated key + timestamp are combined to form the auth payload).
2. Construct the authentication payload: combine the API key with a Unix timestamp (milliseconds) to produce an obfuscated password per Zscaler's documented algorithm.
3. POST to https://.zscaler.net/api/v1/authenticatedSession with JSON body {"apiKey": "", "username": "", "password": "", "timestamp": }.
4. Extract the JSESSIONID cookie from the response and include it as a Cookie header on all subsequent API requests.
5. Call DELETE /authenticatedSession to log out and invalidate the session when done.

List Users

• Method: GET
• URL: /api/v1/users?page=1&pageSize=100&name=<filter>
• Watch out for: Pagination is 1-indexed. Omitting pageSize defaults to 100; max is 1000. Filter by name, dept, or group using query params.

Request example

GET /api/v1/users?pageSize=100&page=1
Cookie: JSESSIONID=<session_id>

Response example

[
  {
    "id": 12345,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "groups": [{"id": 1, "name": "Engineering"}],
    "department": {"id": 10, "name": "R&D"}
  }
]

Get User by ID

• Method: GET
• URL: /api/v1/users/{userId}
• Watch out for: Returns 404 if user does not exist or has been hard-deleted.

Request example

GET /api/v1/users/12345
Cookie: JSESSIONID=<session_id>

Response example

{
  "id": 12345,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "adminUser": false,
  "deleted": false
}

Create User

• Method: POST
• URL: /api/v1/users
• Watch out for: Password is required on creation and must meet complexity requirements. Groups and department objects must reference existing IDs.

Request example

POST /api/v1/users
Content-Type: application/json

{"name":"John Smith","email":"john@example.com",
 "password":"Str0ng!Pass","groups":[{"id":1}],
 "department":{"id":10}}

Response example

{
  "id": 12346,
  "name": "John Smith",
  "email": "john@example.com",
  "groups": [{"id": 1, "name": "Engineering"}]
}

Update User

• Method: PUT
• URL: /api/v1/users/{userId}
• Watch out for: ZIA uses full PUT (not PATCH); omitting optional fields may reset them. Always include the user id in the request body matching the URL parameter.

Request example

PUT /api/v1/users/12346
Content-Type: application/json

{"id":12346,"name":"John A. Smith",
 "email":"john@example.com","groups":[{"id":2}]}

Response example

{
  "id": 12346,
  "name": "John A. Smith",
  "email": "john@example.com",
  "groups": [{"id": 2, "name": "DevOps"}]
}

Delete User

• Method: DELETE
• URL: /api/v1/users/{userId}
• Watch out for: Deletion is permanent (hard delete). There is no soft-delete toggle via this endpoint.

Request example

DELETE /api/v1/users/12346
Cookie: JSESSIONID=<session_id>

Response example

HTTP 204 No Content

Bulk Delete Users

• Method: POST
• URL: /api/v1/users/bulkDelete
• Watch out for: Maximum of 500 IDs per bulk delete request. Exceeding the limit returns an error.

Request example

POST /api/v1/users/bulkDelete
Content-Type: application/json

{"ids": [12345, 12346, 12347]}

Response example

HTTP 204 No Content

Activate Configuration Changes

• Method: POST
• URL: /api/v1/status/activate
• Watch out for: CRITICAL: All create/update/delete operations in ZIA are staged and do not take effect until /status/activate is called. Forgetting this step means changes are not applied to the live policy.

Request example

POST /api/v1/status/activate
Cookie: JSESSIONID=<session_id>

Response example

{
  "status": "ACTIVE"
}

Create Authenticated Session

• Method: POST
• URL: /api/v1/authenticatedSession
• Watch out for: The API key obfuscation algorithm is documented by Zscaler and must be implemented client-side. Using the raw API key directly will result in authentication failure.

Request example

POST /api/v1/authenticatedSession
Content-Type: application/json

{"apiKey":"<obfuscated_key>",
 "username":"admin@example.com",
 "password":"<obfuscated_pw>",
 "timestamp":1700000000000}

Response example

HTTP 200 OK
Set-Cookie: JSESSIONID=abc123; Path=/; HttpOnly

{"obfuscateApiKey": true}

• Rate limits: ZIA enforces per-hour and per-minute API rate limits. Limits vary by endpoint category. Exceeding limits returns HTTP 429.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Official docs note that bulk operations (e.g., updating many users) should include delays between requests. Exact per-endpoint limits are documented in the ZIA API rate limits help article. No standard rate-limit response headers are documented.
• Pagination method: offset
• Default page size: 100
• Max page size: 1000
• Pagination pointer: pageSize / page

• Webhooks available: No
• Webhook notes: Zscaler ZIA does not offer outbound webhooks for user management events. Changes must be polled via the API.
• Alternative event strategy: Use SCIM provisioning from an IdP (Okta, Azure AD) to push user lifecycle events into ZIA automatically, or poll /api/v1/users on a schedule.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://.zscaler.net/scim

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PUT /Groups/{id}, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• SCIM endpoint URL and bearer token are generated within the ZIA Admin Portal under Administration > Authentication > SCIM; the token is shown only once at generation time.
• SSO (SAML) must be configured and enabled before SCIM provisioning can be activated.
• Supported IdPs with documented integration guides: Okta, Azure AD (Entra ID), Ping Identity. Google Workspace and OneLogin are not officially documented.
• SCIM is recommended by Zscaler over SAML Just-In-Time provisioning for full lifecycle management (including deprovisioning).
• SCIM changes in ZIA also require the /status/activate call if made via the native API; however, SCIM-provisioned changes may be applied differently - consult IdP-specific integration guides.
• Available on Enterprise tier; not available on lower ZIA tiers.

Provisioning a new user requires four discrete API calls: authenticate → verify department/group IDs exist → POST /api/v1/users → POST /api/v1/status/activate.

Skipping the activate call leaves the user staged but non-functional;

they cannot authenticate through ZIA until activation completes.

Deprovisioning via the API issues a hard DELETE with no soft-delete toggle and no recovery path.

For teams building an identity graph across SaaS applications, this means the ZIA user record is permanently destroyed on DELETE - any downstream reconciliation must capture the user object before deletion.

SCIM-based deprovisioning via Okta or Azure AD handles the DELETE and activation automatically, removing the need for manual API orchestration.

The update endpoint uses full PUT semantics;

partial updates are not supported.

Omitting optional fields in a PUT body may silently reset existing values.

Bulk deletion accepts a maximum of 500 user IDs per request to /api/v1/users/bulkDelete.

Provision a new employee in ZIA

1. Authenticate: POST /api/v1/authenticatedSession with obfuscated API key and admin credentials to obtain JSESSIONID.
2. Verify the target department and group IDs exist: GET /api/v1/departments and GET /api/v1/groups.
3. Create the user: POST /api/v1/users with name, email, password, groups array, and department object.
4. Activate changes: POST /api/v1/status/activate to push the new user to live policy.
5. Log out: DELETE /api/v1/authenticatedSession.

Watch out for: Skipping the /status/activate call means the user is staged but not active. The user will not be able to authenticate through ZIA until activation.

Deprovision a terminated employee

1. Authenticate and obtain JSESSIONID.
2. Look up the user by email: GET /api/v1/users?name= to retrieve the user ID.
3. Delete the user: DELETE /api/v1/users/{userId}.
4. Activate changes: POST /api/v1/status/activate.
5. Log out.

Watch out for: Deletion via the ZIA API is a hard delete with no recovery. If using SCIM via Okta or Azure AD, deprovisioning the user in the IdP will trigger the DELETE automatically without requiring manual API calls or activation.

Set up SCIM provisioning via Okta

1. Ensure SAML SSO is configured and active in ZIA (prerequisite for SCIM).
2. In ZIA Admin Portal, go to Administration > Authentication > SCIM and enable SCIM provisioning.
3. Copy the generated SCIM endpoint URL and bearer token (token is shown only once - store securely).
4. In Okta, open the Zscaler app integration, navigate to the Provisioning tab, and enter the SCIM base URL and bearer token.
5. Enable provisioning features: Create Users, Update User Attributes, Deactivate Users.
6. Assign users or groups in Okta to trigger initial provisioning to ZIA.

Watch out for: If the SCIM bearer token is lost or regenerated, the Okta integration must be updated with the new token immediately or provisioning will fail silently. SCIM requires Enterprise tier.

The activation requirement is the primary integration trap. Every write operation - create, update, delete - is staged in a pending state. A pipeline that provisions users without calling POST /api/v1/status/activate will appear to succeed (HTTP 200 responses throughout) while producing zero effect on live policy.

This is not surfaced as an error at the write endpoints.

The SCIM bearer token is a secondary trap: it is displayed exactly once at generation time in the Admin Portal. If the token is lost or a new one is regenerated, the existing IdP integration breaks silently - provisioning failures may not surface immediately depending on IdP sync frequency.

Teams integrating ZIA into an identity graph via an MCP server with 60+ deep IT/identity integrations should treat token rotation as a breaking change requiring immediate IdP reconfiguration.

Webhooks are not available in ZIA. User lifecycle events cannot be pushed outbound; all change detection requires polling /api/v1/users on a schedule or relying on SCIM push from a supported IdP.