Configuring the Postman REST API Client

Zscaler supports the macOS, Windows, and Linux versions of the Postman REST API Client app. To learn more about the app and its features, see the Postman app documentation.

If you already have Postman installed and configured, you can download the latest version of the Zscaler Cloud & Branch Connector API Postman collection file from any article within the Reference Guide.

Installing and Configuring Postman for macOS, Windows, or Linux

To install and configure Postman:

The following instructions reference the Windows 64-bit version of the Postman app using the Cloud & Branch Connector API Postman collection file.

  1. Go to the Postman website and download the app for your OS (i.e., macOS, Windows, or Linux).
  2. Install the app.
  3. After installation, open the app. If you do not have an account, you can create one. If you already have an account, log in.
  4. Download the latest version of the Cloud & Branch Connector API Postman collection file from any help article within the Reference Guide.
  5. From your Workspace (Workspaces > My Workspace) or a Workspace you've created, click Import. Alternatively, from the top menu, click File > Import....
  6. In the Import window, make sure that File is selected, then drag and drop the .postman_collection file into the window or click Upload Files. After the file is imported, a new folder (e.g., Cloud & Branch Connector API 6.2), is displayed within Collections.
  7. Next to the environment drop-down menu in the upper-right, ensure that No Environment is selected, then click the Environment quick look icon.
  8. In the Environment section, click Add.
  9. On the New Environment tab that appears, click Add a new variable to add each of the following four new variables:

You can access your base URL (url) and API key (apikey) variable values from the API Key Management page in the Cloud & Branch Connector Admin Portal. To learn more, see API Key Management. Your username is your service account email and your password is your service account password.

VARIABLETYPEINITIAL VALUECURRENT VALUE
urldefaulthttps://connector.<Your Zscaler Cloud Name>/api/v1
apikeydefault<Your API key value><Your API key value>
usernamedefault<Your username>
passworddefault<Your password>
  1. Click Save and close the tab.
  2. Select this environment (e.g., Zscaler Test Environment) from the drop-down menu in the upper-right when using the Cloud & Branch Connector API Postman collection. To learn more, see the Postman app documentation.

Authenticating a Session in Postman

After installing and configuring the Postman app, you can try to authenticate a session.

  1. If you haven’t already done so, select the environment (e.g., Zscaler Test Environment) you previously configured from the drop-down menu in the upper-right. To learn more, see the Postman app documentation.
  2. In the Postman app:
    1. From your Workspace (Workspaces > My Workspace) or a Workspace you've created, click the Collections tab.
    2. Expand the Postman collection you imported previously to view the available endpoints.
    3. Click Authentication > Authenticate - Login.
    4. Click Send.

If your API key and admin credentials were set up properly, a Status 200 OK message is returned.

Making an API Call in Postman

In the following example, you’ll make an API call to the /ecgroup endpoint to list the Cloud & Branch Connector groups available to you.

  1. Make sure that you can authenticate successfully.
  2. In the Cloud & Branch Connector API collection, click Cloud & Branch Connector Groups > GET Cloud & Branch Connector Groups - Get All Groups and VMs.
  3. Click Send.

A successful response to this GET request returns the following example response and a list of Cloud & Branch Connector group information available to you:

  • HTTP/1.1 200 OK
vary: accept-encoding
Content-Encoding: gzip
Content-Type: application/json
Transfer-Encoding: chunked
Date: Mon, 13 Feb 2023 22:01:14 GMT
Keep-Alive: timeout=10
Connection: keep-alive
Server: Zscaler
[
    {
        "id": 63260789,
        "name": "zs-cc-vpc-02de960b4c73a7275-us-west-2a",
        "desc": "Auto created from ami-0c0f8d637a04769ea_i-04f78174f6daf4792",
        "deployType": "CLOUD",
        "status": [
            "CLOUD"
        ],
        "platform": "AWS",
        "awsAvailabilityZone": "US_WEST_2A",
        "location": {
            "id": 63260784,
            "name": "us-west-2-vpc-02de960b4c73a7275"
        },
        "maxEcCount": 0,
        "provTemplate": {
            "id": 316001,
            "name": "aws-zwlc-id"
        },
        "tunnelMode": "UNENCRYPTED",
        "ecVMs": [
            {
                "id": 63260794,
                "name": "zs-cc-vpc-02de960b4c73a7275-us-west-2a-VM-B5bV5",
                "status": [
                    "REGISTERED",
                    "PKG_REPO_REGISTERED"
                ],
                "operationalStatus": "INACTIVE",
                "provTemplate": {
                    "id": 316001,
                    "name": "aws-zwlc-id"
                },
                "formFactor": "SMALL",
                "managementNw": {
                    "id": 350251,
                    "ipStart": "10.1.200.178",
                    "ipEnd": "0.0.0.0",
                    "netmask": "255.255.255.0",
                    "defaultGateway": "10.1.200.1",
                    "nwType": "AUTOMATIC",
                    "dns": {
                        "id": 350249,
                        "ips": [
                            "10.1.0.2"
                        ],
                        "dnsType": "AUTOMATIC"
                    }
                },
                "ecInstances": [
                    {
                        "id": 63260797,
                        "name": "zs-cc-vpc-02de960b4c73a7275-us-west-2a-VM-B5bV5_INSTANCE_1_MnEgQ",
                        "flags": "REGISTERED",
                        "ecInstanceType": "SME",
                        "registerTime": 0,
                        "natIp": "52.38.213.147",
                        "serviceNw": {
                            "id": 350258,
                            "ipStart": "10.1.200.33",
                            "ipEnd": "0.0.0.0",
                            "netmask": "255.255.255.0",
                            "defaultGateway": "10.1.200.1",
                            "nwType": "AUTOMATIC",
                            "dns": {
                                "id": 350257,
                                "ips": [
                                    "10.1.0.2"
                                ],
                                "dnsType": "AUTOMATIC"
                            }
                        },
                        "virtualNw": {
                            "id": 350256,
                            "ipStart": "0.0.0.0",
                            "ipEnd": "0.0.0.0",
                            "netmask": "0.0.0.0",
                            "defaultGateway": "0.0.0.0",
                            "nwType": "AUTOMATIC",
                            "dns": {
                                "id": 350254,
                                "ips": [
                                    "0.0.0.0"
                                ],
                                "dnsType": "AUTOMATIC"
                            }
                        }
                    }
                ],
                "cityGeoId": 5714964,
                "natIp": "52.38.213.147",
                "ziaGateway": "165.225.50.12",
                "zpaBroker": "136.226.57.254",
                "buildVersion": "346637",
                "lastUpgradeTime": 1678010276,
                "upgradeStatus": 0,
                "upgradeStartTime": 0,
                "upgradeEndTime": 7200,
                "upgradeDayOfWeek": 1,
                "haStatus": "DISABLED"
            }
        ]
    },
    {
        "id": 63260807,
        "name": "zs-cc-vpc-07c37249a25154547-us-east-2a",
        "desc": "Auto created from ami-06a12e35f23ca5f7a_i-0bf0bbc515f4c7f64",
        "deployType": "CLOUD",
        "status": [
            "CLOUD"
        ],
        "platform": "AWS",
        "awsAvailabilityZone": "US_EAST_2A",
        "location": {
            "id": 63260805,
            "name": "us-east-2-vpc-07c37249a25154547"
        },
        "maxEcCount": 0,
        "provTemplate": {
            "id": 316001,
            "name": "aws-zwlc-id"
        },
        "tunnelMode": "UNENCRYPTED",
        "ecVMs": [
            {
                "id": 63260809,
                "name": "zs-cc-vpc-07c37249a25154547-us-east-2a-VM-0TbUx",
                "status": [
                    "REGISTERED",
                    "PKG_REPO_REGISTERED"
                ],
                "operationalStatus": "INACTIVE",
                "provTemplate": {
                    "id": 316001,
                    "name": "aws-zwlc-id"
                },
                "formFactor": "SMALL",
                "managementNw": {
                    "id": 350260,
                    "ipStart": "10.1.200.201",
                    "ipEnd": "0.0.0.0",
                    "netmask": "255.255.255.0",
                    "defaultGateway": "10.1.200.1",
                    "nwType": "AUTOMATIC",
                    "dns": {
                        "id": 350259,
                        "ips": [
                            "10.1.0.2"
                        ],
                        "dnsType": "AUTOMATIC"
                    }
                },
                "ecInstances": [
                    {
                        "id": 63260813,
                        "name": "zs-cc-vpc-07c37249a25154547-us-east-2a-VM-0TbUx_INSTANCE_1_4emcc",
                        "flags": "REGISTERED",
                        "ecInstanceType": "SME",
                        "registerTime": 0,
                        "natIp": "3.20.194.248",
                        "serviceNw": {
                            "id": 350268,
                            "ipStart": "10.1.200.105",
                            "ipEnd": "0.0.0.0",
                            "netmask": "255.255.255.0",
                            "defaultGateway": "10.1.200.1",
                            "nwType": "AUTOMATIC",
                            "dns": {
                                "id": 350266,
                                "ips": [
                                    "10.1.0.2"
                                ],
                                "dnsType": "AUTOMATIC"
                            }
                        },
                        "virtualNw": {
                            "id": 350264,
                            "ipStart": "0.0.0.0",
                            "ipEnd": "0.0.0.0",
                            "netmask": "0.0.0.0",
                            "defaultGateway": "0.0.0.0",
                            "nwType": "AUTOMATIC",
                            "dns": {
                                "id": 350263,
                                "ips": [
                                    "0.0.0.0"
                                ],
                                "dnsType": "AUTOMATIC"
                            }
                        }
                    }
                ],
                "cityGeoId": 4509177,
                "natIp": "3.20.194.248",
                "ziaGateway": "165.225.8.22",
                "zpaBroker": "165.225.100.203",
                "buildVersion": "346637",
                "lastUpgradeTime": 1677999488,
                "upgradeStatus": 0,
                "upgradeStartTime": 0,
                "upgradeEndTime": 7200,
                "upgradeDayOfWeek": 1,
                "haStatus": "DISABLED"
            }
        ]
    }
]
    Close

By default, the session is terminated after 30 minutes and reauthentication is required. So, be sure to keep your idle time to less than 30 minutes.