Configuring Servers Using API

This article provides information on managing Zscaler Private Access (ZPA) server use cases using APIs. All APIs are rate limited. To learn more, see ZPA API Rate Limits.

Prerequisite API Call

Before you create a new server, you must get the required details for server groups. To learn more, see Configuring Server Groups Using API.

Creating a New Server

To add a new server:

Send a POST request to the following endpoint in the server-controller: /mgmtconfig/v1/admin/customers/{customerId}/server.
Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057615512764416/server.
Include the request headers to provide information about the request context:
- Content-Type: application/json
- Authorization: Bearer <access_token>
Use the following JSON payload to create the server and provide the following information:
- name: The name of the server.
- enabled: Indicates the status of the server (true, false).
- address: Indicates the server IP or the domain.
- Information about the associated server groups.

A successful response returns code 201. To learn more, see ZPA API Codes.

NOTE

You choose the server criteria you want to include in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

JSON Payload

{
"name":"server_name",
"description":"description",
"enabled":true,
"address":"serverIP or domain",
"appServerGroupIds":[
     "serverGroupId1",
     "serverGroupId2"
]
}

Example Response

{
  "id": "217246660303024816",
  "creationTime": "1614272495",
  "modifiedBy": "217246660303024815",
  "name": "server_example",
  "address": "192.168.1.1",
  "enabled": true,
  "description": "Test App Server",
  "appServerGroupIds": [
    "217246660303020476",
    "217246660302996731"
  ],
  "configSpace": "DEFAULT"
}

Adding Field Descriptions

The following table includes descriptions of available fields you can use for the server use cases:

Field	Description	Required	Value
name	This field defines the name of the server	Yes	String
description	This field defines the description of the server	No	String
enabled	This field defines the status of the server	Yes	true, false
address	This field defines the domain or IP address of the server	Yes	String
appServerGroupIds	This field defines the list of server groups IDs	No	List of strings
microtenantId	The unique identifier of the Microtenant for the ZPA tenant. If you are within a Microtenant, you must pass the `microtenantId` field when making an API call to retrieve data from that Microtenant. The `microtenantId` can be obtained in the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations are limited when you are within a Microtenant. If you are within the Default Microtenant, pass `microtenantId` as `0` when making requests to retrieve data from the Default Microtenant. Pass `microtenantId` as null to retrieve data from all Microtenants associated with the tenant. If the `microtenantId` is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.	No	Integer

Getting Details for a Particular Server

To get details for a particular server:

Send a GET request to the following endpoint in the server-controller: /mgmtconfig/v1/admin/customers/{customerId}/server/{serverId}.
Provide the following values in the request endpoint:
- customerId: The ZPA tenant ID of the customer.
- serverId: The ID of the server.
For example: /mgmtconfig/v1/admin/customers/72057615512764416/server/72057615512764544.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response

{
  "id": "72057615512764544",
  "creationTime": "1579729244",
  "modifiedBy": "72057615512764417",
  "name": "PB App",
  "address": "10.0.0.190",
  "enabled": true,
  "appServerGroupAssociations": {
    "72057615512764545": "PB App"
  },
  "configSpace": "DEFAULT"
}

Getting Details for All Servers

To get details for all servers:

Send a GET request to the following endpoint in the server-controller: /mgmtconfig/v1/admin/customers/{customerId}/server.
Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057615512764416/server.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response

{
  "totalPages": "1",
  "list": [
    {
      "id": "72057615512764544",
      "creationTime": "1579729244",
      "modifiedBy": "72057615512764417",
      "name": "PB App",
      "address": "10.0.0.190",
      "enabled": true,
      "appServerGroupAssociations": {
        "72057615512764545": "PB App"
      },
      "configSpace": "DEFAULT"
    },
    {
      "id": "72057615512764472",
      "creationTime": "1560983093",
      "modifiedBy": "72057615512764447",
      "name": "srv1",
      "address": "10.0.3.7",
      "enabled": true,
      "appServerGroupAssociations": {
        "72057615512764473": "srvgrp1"
      },
      "configSpace": "DEFAULT"
    },
    {
      "id": "72057615512764604",
      "creationTime": "1612389365",
      "modifiedBy": "72057615512764603",
      "name": "TestApplicationServer",
      "address": "10.0.0.190",
      "enabled": true,
      "description": "string",
      "appServerGroupAssociations": {
        "72057615512764545": "PB App",
        "72057615512764418": "Server Group",
        "72057615512764473": "srvgrp1"
      },
      "configSpace": "DEFAULT"
    }
  ]
}

Pagination

This API supports pagination. To get a paginated response:

Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/server?page=1&pagesize=20 .
Provide the following in the request endpoint:
- customerId: The ZPA tenant ID of the customer.
- Valid values for page and page size parameters.
For example: /mgmtconfig/v1/admin/customers/144118148382065089/server?page=1&pagesize=2.

NOTE

If not provided, the default page size is 20. The maximum page size is 500.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response

{
  "totalPages": "7",
  "list": [
    {
      "id": "144118148382065089",
      "creationTime": "1549613557",
      "modifiedBy": "144118148382064667",
      "name": "akk",
      "address": "10.65.1.220",
      "enabled": true,
      "appServerGroupIds": [
        "144118148382065088"
      ],
      "configSpace": "DEFAULT"
    },
    {
      "id": "144118148382065094",
      "modifiedTime": "1591164519",
      "creationTime": "1549616584",
      "modifiedBy": "144118148382064642",
      "name": "app2.lanukcorp.com",
      "address": "10.0.1.145",
      "enabled": true,
      "appServerGroupIds": [
        "144118148382065093"
      ],
      "configSpace": "DEFAULT"
    }
  ]
}

Search Option

This API supports a search option to search by features and fields. To search by features and fields:

Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/73186051597795328/server&search={searchString}.
Provide the following in the request endpoint:
- customerId: The ZPA tenant ID of the customer.
- Valid search string values. The search string values are in the format fieldName operator fieldValue. Only search string values that correspond to the values for valid fields and filters are supported. For example, the string address%20LIKE%20test is supported for the Domain or IP Address filter, using the **Contains **(LIKE) operator, for the filter value test.
For example: /mgmtconfig/v1/admin/customers/73186051597795328/server&search=address%20LIKE%20test.

NOTE

If you use the ZPA API PortaI or the API Reference to make your API calls, the search field string does not require any characters. For example, address%20LIKE%20test is address LIKE test.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response

{
  "totalPages": "1",
  "totalCount": "1",
  "list": [
    {
      "id": "72057594037996318",
      "creationTime": "1615454081",
      "modifiedBy": "72057594037957297",
      "name": "Test Error1",
      "address": "newtest.com",
      "enabled": true,
      "description": "&amp;",
      "appServerGroupIds": [
        "72057594037988996"
      ],
      "configSpace": "DEFAULT"
    }
  ]
}

Updating Server Details

To update the server:

Use the updated JSON payload from the Creating a New Server section and send a PUT request to the following endpoint in the server-controller: /mgmtconfig/v1/admin/customers/{customerId}/server/{serverId}.
Provide the following values in the request endpoint:
- customerId: The ZPA tenant ID of the customer.
- serverId: The server ID captured in the Creating a New Server section.
For example: /mgmtconfig/v1/admin/customers/72057615512764416/server/72057615512764544.

Refer to the Adding Field Descriptions section for supported values.

A successful response yields code 204, meaning the server is updated. To learn more, see ZPA API Codes.

JSON Payload

{
  "address": "string",
  "appServerGroupIds": [
    "string"
  ],
  "configSpace": "DEFAULT",
  "creationTime": 0,
  "description": "string",
  "enabled": true,
  "id": 0,
  "modifiedBy": 0,
  "modifiedTime": 0,
  "name": "string"
}

Deleting a Server

To delete a server:

Send a DELETE request to the following endpoint in the server-controller: /mgmtconfig/v1/admin/customers/{customerId}/server/{serverId}.
Provide the following values in the request endpoint:
- customerId: The ZPA tenant ID of the customer.
- serverId: The server ID captured in the Creating a New Server section.
For example: /mgmtconfig/v1/admin/customers/72057615512764416/server/72057615512764544.

CAUTION

An object that is referenced in another object cannot be deleted. Error code 400 is returned in this situation. To learn more, see ZPA API Codes.

A successful response yields code 204, meaning the server is deleted.

Error Code 400

{
    "params": [
        "Application",
        "app 3 created on postman feb 5_edited"
    ],
    "id": "resource.referenced",
    "reason": "Resource is being referenced in Application : app 3 created on postman feb 5_edited."
}

Prerequisite API Call

Creating a New Server

JSON Payload​

Example Response​

Adding Field Descriptions

Getting Details for a Particular Server

Example Response​

Getting Details for All Servers

Example Response​

Pagination​

Example Response​

Search Option​

Example Response​

Updating Server Details

JSON Payload​

Deleting a Server

Error Code 400​

JSON Payload

Example Response

Example Response

Example Response

Pagination

Example Response

Search Option

Example Response

JSON Payload

Error Code 400