Configuring Server Groups Using API

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

Prerequisite API Call

Before you create a new server group, you must get the required list of App Connector groups. To learn more, see Configuring App Connector Groups Using API.

Creating a New Server Group

To add a new server group:

  1. Send a POST request to the following endpoint in the server-group-controller: /mgmtconfig/v1/admin/customers/{customerId}/serverGroup.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057615512764416/serverGroup.
  3. Include the request headers to provide information about the request context:
  • Content-Type: application/json
  • Authorization: Bearer <access_token>
  1. Use the entire JSON payload to create a server group and provide the required details:
  • name: The name of the server group.
  • enabled: Indicates if the server group is enabled (true) or disabled (false).
  • dynamicDiscovery: This field controls dynamic discovery of the servers.
  • Associated App Connector groups
    • Provide the associated server list only when the auto-server-discovery is disabled (i.e., dynamicDiscovery= false)
  • {
   "enabled":true,
   "dynamicDiscovery":false,
   "name":"<serverGroupName>",
   "description":"desc",
   "servers":[
      {
         "id":"<serverId1>",
      },
      {
         "id":"<serverId2>",
      }
   ],
   "appConnectorGroups":[
      {
         "id":"<appConnectorGroupId1>",
      },
      {
         "id":"<appConnectorGroupId2>",
      }
   ]
}
    Close
  • {
  "id": "217246660303024819",
  "enabled": true,
  "name": "Example Test Server Group",
  "description": "Example Server Group for testing",
  "servers": [
    {
      "id": "217246660302995951",
      "configSpace": "DEFAULT"
    },
    {
      "id": "217246660303024816",
      "configSpace": "DEFAULT"
    }
  ],
  "ipAnchored": false,
  "configSpace": "DEFAULT",
  "dynamicDiscovery": false,
  "appConnectorGroups": [
    {
      "id": "217246660303020475",
      "name": "11113",
      "enabled": true,
      "siemAppConnectorGroup": false
    },
    {
      "id": "217246660303023146",
      "name": "1 mp connector grp",
      "enabled": true,
      "siemAppConnectorGroup": false
    }
  ]
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

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

Adding Field Descriptions

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

FieldDescriptionRequiredValue
nameThis field defines the name of the server groupYesString
descriptionThis field is the description of the server groupNoString
enabledThis field defines if the server group is enabled or disabledNotrue, false
dynamicDiscoveryThis field controls dynamic discovery of the serversYestrue, false
appConnectorGroupsThis field is a json array of App Connector Group IDsYesAccepts values in the format:
{
"id":"<appConnectorGrpId>",
}
serversThis field is a list of servers that are applicable only when dynamic discovery is disabled. Server name is required only in cases where the new servers need to be created in this API. For existing servers, pass only the serverId.NoAccepts values in the format:
{
"id":"<serverId>",
}
microtenantIdThe 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.NoInteger

Getting Details for a Particular Server Group

To get details for a particular server group:

  1. Send a GET request to the following endpoint in the server-group-controller: /mgmtconfig/v1/admin/customers/{customerId}/serverGroup/{groupId}.
  2. Provide the following values in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • groupId: The ID of the particular server group you want to get details for.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/serverGroup/72057615512764618.

  • {
  "creationTime": "1612476914",
  "modifiedBy": "72057615512764617",
  "id": "72057615512764618",
  "enabled": false,
  "name": "TestAppServerGrp",
  "learningEnabled": false,
  "description": "string",
  "ipAnchored": false,
  "configSpace": "DEFAULT"
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting Details for All Server Groups

To get details for all the server groups:

  1. Send a GET request to the following endpoint in the server-group-controller: /mgmtconfig/v1/admin/customers/{customerId}/serverGroup.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057615512764416/serverGroup.
  • {
  "totalPages": "1",
  "list": [
    {
      "modifiedTime": "1612391262",
      "creationTime": "1574113633",
      "modifiedBy": "72057615512764552",
      "id": "72057615512764532",
      "enabled": true,
      "name": "AWS Connector",
      "learningEnabled": true,
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "connectorGroups": [
        {
          "id": "72057615512764441",
          "modifiedTime": "1610747816",
          "creationTime": "1553590280",
          "modifiedBy": "72057594037928174",
          "name": "AWS",
          "enabled": true,
          "location": "Oregon City, OR 97045, USA",
          "cityCountry": "Oregon City, US",
          "countryCode": "US",
          "siemConnectorGroup": false
        }
      ]
    },
    {
      "creationTime": "1579729263",
      "modifiedBy": "72057615512764417",
      "id": "72057615512764545",
      "enabled": true,
      "name": "PB App",
      "learningEnabled": false,
      "servers": [
        {
          "id": "72057615512764544",
          "creationTime": "1579729244",
          "modifiedBy": "72057615512764417",
          "name": "PB App",
          "address": "10.0.0.190",
          "enabled": true,
          "configSpace": "DEFAULT"
        },
        {
          "id": "72057615512764604",
          "creationTime": "1612389365",
          "modifiedBy": "72057615512764603",
          "name": "TestApplicationServer",
          "address": "10.0.0.190",
          "enabled": true,
          "description": "string",
          "configSpace": "DEFAULT"
        }
      ],
      "applications": [
        {
          "id": "72057615512764533",
          "name": "PB App"
        }
      ],
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "connectorGroups": [
        {
          "id": "72057615512764441",
          "modifiedTime": "1610747816",
          "creationTime": "1553590280",
          "modifiedBy": "72057594037928174",
          "name": "AWS",
          "enabled": true,
          "location": "Oregon City, OR 97045, USA",
          "cityCountry": "Oregon City, US",
          "countryCode": "US",
          "siemConnectorGroup": false
        }
      ]
    },
    {
      "modifiedTime": "1560279822",
      "creationTime": "1551291935",
      "modifiedBy": "72057615512764417",
      "id": "72057615512764418",
      "enabled": true,
      "name": "Server Group",
      "learningEnabled": true,
      "servers": [
        {
          "id": "72057615512764604",
          "creationTime": "1612389365",
          "modifiedBy": "72057615512764603",
          "name": "TestApplicationServer",
          "address": "10.0.0.190",
          "enabled": true,
          "description": "string",
          "configSpace": "DEFAULT"
        }
      ],
      "applications": [
        {
          "id": "72057615512764419",
          "name": "Internal Application"
        }
      ],
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "connectorGroups": [
        {
          "id": "72057615512764449",
          "modifiedTime": "1610747816",
          "creationTime": "1560278889",
          "modifiedBy": "72057594037928174",
          "name": "Azure",
          "enabled": true,
          "location": "Oregon, USA",
          "cityCountry": "Brothers, US",
          "countryCode": "US",
          "siemConnectorGroup": false
        }
      ]
    },
    {
      "creationTime": "1560983270",
      "modifiedBy": "72057615512764447",
      "id": "72057615512764473",
      "enabled": true,
      "name": "srvgrp1",
      "learningEnabled": false,
      "servers": [
        {
          "id": "72057615512764472",
          "creationTime": "1560983093",
          "modifiedBy": "72057615512764447",
          "name": "srv1",
          "address": "10.0.3.7",
          "enabled": true,
          "configSpace": "DEFAULT"
        },
        {
          "id": "72057615512764604",
          "creationTime": "1612389365",
          "modifiedBy": "72057615512764603",
          "name": "TestApplicationServer",
          "address": "10.0.0.190",
          "enabled": true,
          "description": "string",
          "configSpace": "DEFAULT"
        }
      ],
      "applications": [
        {
          "id": "72057615512764474",
          "name": "app1"
        },
        {
          "id": "72057615512764478",
          "name": "app2"
        }
      ],
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "connectorGroups": [
        {
          "id": "72057615512764449",
          "modifiedTime": "1610747816",
          "creationTime": "1560278889",
          "modifiedBy": "72057594037928174",
          "name": "Azure",
          "enabled": true,
          "location": "Oregon, USA",
          "cityCountry": "Brothers, US",
          "countryCode": "US",
          "siemConnectorGroup": false
        }
      ]
    }
  ]
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

This API supports pagination. To get a paginated response:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/serverGroup?page=1&pagesize=20.
  2. 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/72057615512764416/serverGroup?page=1&pagesize=2.

  • {
  "totalPages": "11",
  "list": [
    {
      "modifiedTime": "1584421166",
      "creationTime": "1492592504",
      "modifiedBy": "144118148382064930",
      "id": "144118148382064812",
      "enabled": true,
      "name": "161_sg",
      "description": "DESC - u",
      "servers": [
        {
          "id": "144118148382064811",
          "modifiedTime": "1498248533",
          "creationTime": "1492592483",
          "modifiedBy": "144118148382064667",
          "name": "Server_161",
          "address": "10.66.62.243",
          "enabled": true,
          "description": "DESC",
          "configSpace": "DEFAULT"
        }
      ],
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "dynamicDiscovery": false,
      "appConnectorGroups": [
        {
          "id": "144118148382064739",
          "creationTime": "1471333758",
          "modifiedBy": "144118148382064667",
          "name": "New_Connector",
          "enabled": true,
          "description": "desc",
          "overrideVersionProfile": false,
          "dnsQueryType": "IPV4_IPV6",
          "lssAppConnectorGroup": false
        }
      ]
    },
    {
      "creationTime": "1549613557",
      "modifiedBy": "144118148382064667",
      "id": "144118148382065088",
      "enabled": true,
      "name": "akk",
      "servers": [
        {
          "id": "144118148382065089",
          "creationTime": "1549613557",
          "modifiedBy": "144118148382064667",
          "name": "akk",
          "address": "10.65.1.220",
          "enabled": true,
          "configSpace": "DEFAULT"
        }
      ],
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "dynamicDiscovery": false,
      "appConnectorGroups": [
        {
          "id": "144118148382064835",
          "modifiedTime": "1611094156",
          "creationTime": "1499715985",
          "modifiedBy": "72057594037928187",
          "name": "Azure Connectors",
          "enabled": true,
          "versionProfileId": "72057594037928267",
          "overrideVersionProfile": true,
          "location": "California, USA",
          "dnsQueryType": "IPV4_IPV6",
          "cityCountry": "Sanger, US",
          "countryCode": "US",
          "lssAppConnectorGroup": false
        }
      ]
    }
  ]
}
    Close

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 API Response Codes and Error Messages.

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

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/73186051597795328/serverGroup&search={searchString}.
  2. 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 name%20LIKE%20test is supported for the Name filter, using the Contains (LIKE) operator, for the filter value test.

For example: /mgmtconfig/v1/admin/customers/73186051597795328/serverGroup&search=name%20LIKE%20test.

  • {
  "totalPages": "16",
  "totalCount": "16",
  "list": [
    {
      "creationTime": "1657606560",
      "modifiedBy": "72057594038606761",
      "id": "72057594038606770",
      "enabled": true,
      "name": "test-group1",
      "description": "Testing",
      "applications": [
        {
          "id": "72057594038606771",
          "name": "test-segment"
        }
      ],
      "ipAnchored": false,
      "configSpace": "DEFAULT",
      "microtenantName": "Default",
      "dynamicDiscovery": true,
      "appConnectorGroups": [
        {
          "id": "72057594038011105",
          "modifiedTime": "1664486317",
          "creationTime": "1620326590",
          "modifiedBy": "72057594037982266",
          "name": "App_Connector_Test_1",
          "enabled": true,
          "versionProfileId": "0",
          "overrideVersionProfile": false,
          "location": "1234 Test Rd, Bronx, NY 10466, USA",
          "dnsQueryType": "IPV4_IPV6",
          "cityCountry": "New York, US",
          "countryCode": "US",
          "tcpQuickAckApp": false,
          "tcpQuickAckAssistant": false,
          "tcpQuickAckReadAssistant": false,
          "ipAcl": [
            "::/0"
          ],
          "lssAppConnectorGroup": false
        }
      ]
    }
  ]
}
    Close

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

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Updating Server Group Details

To update the server group details:

  1. Use the updated JSON payload from the Creating a New Server Group section and send a PUT request to the following endpoint in the server-group-controller: /mgmtconfig/v1/admin/customers/{customerId}/serverGroup/{groupId}.

For example: /mgmtconfig/v1/admin/customers/72057615512764416/serverGroup/72057615512764618.

  1. Provide the required details:
  • name: The name of the Server Group.
  • enabled: Indicates the status of the Server Group is enabled (true) or disabled (false).
  • dynamicDiscovery: This field controls dynamic discovery of the servers.
  • Information about the associated App Connector Groups.
    • Provide the associated server list only when the auto-server-discovery is disabled (i.e., learningEnabled is false)

Refer to the Adding Field Descriptions section for supported values.

  1. Provide the following values in the request endpoint:

For example: /mgmtconfig/v1/admin/customers/72057615512764416/serverGroup/72057615512764618.

  • {
   "enabled":true,
   "dynamicDiscovery":false,
   "name":"<serverGroupName>",
   "description":"desc",
   "servers":[
      {
         "id":"<serverId1>"
      },
      {
         "id":"<serverId2>"
      }
   ],
   "appConnectorGroups":[
      {
         "id":"<appConnectorGroupId1>"
      },
      {
         "id":"<appConnectorGroupId2>"
      }
   ]
}
    Close

A successful response returns code 204, meaning the server group is updated. To learn more, see API Response Codes and Error Messages.

If a server group is configured using Zscaler Deception, then the update and delete options are unavailable.

Deleting a Server Group

To delete a server group:

  1. Send a DELETE request to the following endpoint in the server-group-controller: /mgmtconfig/v1/admin/customers/{customerId}/serverGroup/{groupId}.
  2. Provide the following values in the request endpoint:

For example: /mgmtconfig/v1/admin/customers/72057615512764416/serverGroup/72057615512764618.

An object that is referenced in another object cannot be deleted. Error code 400 is returned in this situation.

  • {
    "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."
}
    Close

A successful response returns code 204, meaning the application server group is deleted. To learn more, see API Response Codes and Error Messages.

If a server group is configured using Zscaler Deception, then the update and delete options are unavailable.