icon-oneapi.svg
OneAPI

Configuring the Postman REST API Client

Zscaler offers a Postman collection that simplifies interaction with its API endpoints, allowing you to easily test and manage API requests within the Postman application. This collection is designed to work seamlessly with all APIs included in Zscaler OneAPI, requiring minimal configurations from the user. It includes preconfigured request scripts for authentication, along with prebuilt payloads and parameters where necessary. Additionally, the collection comes with all the essential preset variables, ensuring a smooth experience. This guide provides information on how to set up your Postman application and make API requests, along with a link to download the Postman collection for OneAPI.

  • The Postman collection provided by Zscaler can be used on Windows, Linux, and macOS versions of the Postman REST API client.
  • Before getting started, ensure that you have obtained the API client information, such as client ID and client secret, from the ZIdentity Admin Portal. This article follows the client secret flow of authentication which is supported by the Postman application.

To learn more about rate limiting and HTTP status codes, see Understanding Rate Limiting and Understanding Response Codes & Error Messages. If you encounter any issues with the API, contact Zscaler Support.

Installing and Configuring Postman for Windows, Linux, or macOS

To install the Postman application:

  1. Go to the Download Postman page and download the application for your OS (i.e., Windows, Linux, or macOS).

    For this example, the Postman application for 64-bit version Windows is used to illustrate the instructions.

  2. Open the downloaded Postman setup file to install the application. After installation, the login window for signing in to Postman appears.

  3. In the login window, create an account, and sign in using your account. If you already have a Postman account, log in to Postman with your existing credentials.

Adding OneAPI Postman Collection

After logging in to Postman, you can import the Postman collection for OneAPI. To add the collection to the Postman application:

  1. Download the latest Postman collection for OneAPI from the following link: Download JSON
  2. In the Postman application, go to your preferred workspace. The default workspace is My Workspace.

  3. Click Import. Alternatively, you can go to the application menu on the top-left corner and click File > Import....

  4. In the import window that appears, select your .postman_collection file or drag the file to the import window.

    The Postman collection for OneAPI is imported into the application. A new folder with the name used within the Postman collection file (e.g., OneAPI) is displayed within Collections in the left-side navigation.

Setting Up Variables and Environments

Before you make API calls using the collection in Postman, you need to configure a set of variables that helps reuse specific values across your API requests. You can configure variables at different scopes in Postman. For OneAPI, it is recommended to configure variables either at the collection level or at the environment level. To learn more, refer to the Postman documentation.

The Postman collection provided by Zscaler comes preconfigured with variables at the collection level to help you get started quickly by specifying values for these variables. Alternatively, you can create an environment with the same set of variables and reference the variables in your API requests by selecting the environment. Using environments is especially recommended if you are working across multiple OneAPI collections (e.g., different environments can be used for testing and production purposes). The following sections explain how to set up the predefined collection variables or create an environment with the same set of variables.

Configuring Collection Variables

To configure collection variables:

  1. In the workspace where you added your collection, go to Collections.
  2. Click the OneAPI collection folder name.

  3. Go to the Variables tab displayed for the collection.

    The variables present in the collection are displayed in a table, with values prepopulated for variables that are universal to all organizations (e.g., base URL for APIs).

  4. For variables that contain values specific to the organization, such as client ID, client secret, ZIdentity's token endpoint, etc., you need to configure the values manually. For each variable, enter its value into the Initial value column, then re-enter the same value in the Current value column.

    Variable NameDescription
    zIdentityBaseUrlRepresents ZIdentity's token endpoint: https://<Vanity Domain>.zslogin.net, where <Vanity Domain> refers to the domain name used by your organization.
    clientIDAPI client ID obtained from the ZIdentity Admin Portal.
    clientSecretAPI client secret obtained from the ZIdentity Admin Portal.
    customerIdZPA tenant ID of the customer obtained from the ZIdentity Admin Portal or the ZPA Admin Portal. To learn how to obtain the ZPA customer ID, see Getting Started. This configuration is applicable only to ZPA API clients.
    oneAPIBaseUrlThis variable is prepopulated with the base URL for OneAPI: https://api.zsapi.net.
    ZIABaseThis variable is prepopulated with the base URL for Zscaler Internet Access (ZIA) API: {{oneAPIBaseUrl}}/zia/api/v1, which would become https://api.zsapi.net/zia/api/v1 when the {{oneAPIBaseUrl}} variable is replaced with its value.
    ZPABaseThis variable is prepopulated with the base URL for Zscaler Private Access (ZPA) API: {{oneAPIBaseUrl}}/zpa, which would become https://api.zsapi.net/zpa when the {{oneAPIBaseUrl}} variable is replaced with its value.
    ZCCBaseThis variable is prepopulated with the base URL for Zscaler Client Connector API: {{oneAPIBaseUrl}}/zcc/papi/public, which would become https://api.zsapi.net/zcc/papi/public when the {{oneAPIBaseUrl}} variable is replaced with its value.
    ZTWBaseThis variable is prepopulated with the base URL for Cloud & Branch Connector API: {{oneAPIBaseUrl}}/ztw/api/v1, which would become https://api.zsapi.net/ztw/api/v1 when the {{oneAPIBaseUrl}} variable is replaced with its value.
    Close

    Ensure that the variables are selected and configured properly.

  5. Click the Save icon displayed in the top right of the collection window.

Creating an Environment

To add an environment:

  1. In the workspace where you added your collection, go to Environments in the workspace .

  2. Click Create Environment or click the Add icon.

    Alternatively, you can click the Environment quick look icon on the right panel from any location of the Postman application.

    A new environment is added and opens in a tab.

  3. On the environment tab, enter a descriptive name for the environment (e.g., OneAPI) where the current generic name is highlighted.

  4. In the variables table, add the variables listed in the table below and configure their values. For each variable, enter its value into the Initial value column, and the same value is automatically populated in the Current value column.

    Variable NameDescription
    zIdentityBaseUrlRepresents ZIdentity's token endpoint: https://<Vanity Domain>.zslogin.net, where <Vanity Domain> refers to the domain name used by your organization.
    clientIDAPI client ID obtained from the ZIdentity Admin Portal.
    clientSecretAPI client secret obtained from the ZIdentity Admin Portal.
    customerIdZPA tenant ID of the customer obtained from the ZIdentity Admin Portal or the ZPA Admin Portal. To learn how to obtain the ZPA customer ID, see Getting Started. This configuration is applicable only to ZPA API clients.
    oneAPIBaseUrlBase URL for OneAPI: https://api.zsapi.net.
    ZIABaseBase URL for Zscaler Internet Access (ZIA) API: {{oneAPIBaseUrl}}/zia/api/v1.
    ZPABaseBase URL for Zscaler Private Access (ZPA) API: {{oneAPIBaseUrl}}/zpa.
    ZCCBaseBase URL for Zscaler Client Connector API: {{oneAPIBaseUrl}}/zcc/papi/public.
    ZTWBaseBase URL for Cloud & Branch Connector API: {{oneAPIBaseUrl}}/ztw/api/v1.
    Close

    Ensure that the variables are selected, the Type is set to default, and they are configured properly.

  5. Click Save in the top right of the environment tab.

Authenticating a Session in Postman

Before you make an API call from Postman, you have to authenticate a session by sending a POST request to ZIdentity's token endpoint and obtaining an authorization token (i.e., bearer access token) in exchange for the API client credentials. The Postman collection provided by Zscaler comes prebuilt with the authorization request and associated configurations, simplifying the process of getting access tokens. In addition, authorization is configured at the collection level, which allows you to get the access token once and automatically use it for all requests in the collection.

  • The authorization request and token configuration use variables such as zIdentityBaseUrl, clientID, and clientSecret, so ensure that you have configured these variables with appropriate values before sending the request. To learn more, see Setting Up Variables and Environments.
  • The instructions in this section follow the client secret flow of authentication which is supported by the Postman application. The other method of authentication that can be used for OneAPI, Private Key JWT authentication, is not supported by Postman.

To send an authorization request to retrieve the access token:

  1. In the workspace where you added your collection, go to Collections.
  2. Click the OneAPI collection folder name.

  3. Go to the Authorization tab displayed for the collection.

  4. Review the authorization details that are prepopulated for the OAuth 2.0 authentication type and verify the token configuration details.

    Under Advanced, ensure that the audience parameter configured with the value https://api.zscaler.com/ is selected for both Token Request and Refresh Request.

  5. If you are using an environment for your variables, ensure that the correct environment is selected in the top-right corner.

  6. After verifying the authorization details, click Get New Access Token.

    If authentication is successful, an access token is returned and appears in a window. This window displays the complete token details, such as the access token, token type (i.e., bearer token), token expiration, etc.

  7. Optionally, you can rename the token for easy identification using the Token Name field in the window.
  8. To use the access token in your API requests, click Use Token in the window.

  9. On the Authorization tab, the access token name is selected in the drop-down menu and the token is populated in the Token field under Current Token.

    When the access token is selected to be used, the Auto-refresh Token option is automatically enabled.

This authorization token is automatically passed onto each request made from the collection to the OneAPI resources.

Making an API Call in Postman

Before making API calls, ensure that the API is authenticated.

If you are using an environment to reference your variables, select the appropriate environment configured for OneAPI from the environment drop-down menu in the top-right corner.

The steps to making calls to OneAPI are explained using the following examples:

  • The following example shows how to look up categories in ZIA for a specified list of URLs using /urlLookup.

    1. In the workspace where you added your collection, go to Collections.
    2. Click the OneAPI folder and then click the Zscaler Internet Access (ZIA) folder.

    3. Go to URL categories > POST URL Lookup. The /urlLookup request appears on the right pane.

      Click the request's Body tab to view the list of reconfigured URLs for which the lookup operation must be performed. You can look up a maximum of 100 URLs per request, with each URL not exceeding 1,024 characters.

    4. Click Send.
      If the request is successful, you should receive a Status 200 OK message and a response Body that looks as follows:

    Close

  • In the following example, we get the global policy set ID for a specific ZPA tenant by sending a GET request to the endpoint /mgmtconfig/v1/admin/customers/:customerId/policySet/global.

    1. In the workspace where you added your collection, go to Collections.
    2. Click the OneAPI folder and then click the Zscaler Private Access (ZPA) folder.
    3. Go to Policy Set > Get the global policy. The /mgmtconfig/v1/admin/customers/:customerId/policySet/global request appears on the right pane.

    4. On the Params tab, verify that you are using the correct customerId. To learn more, see About API Key Management.

      Under Path Variables, enter your customer ID into the Value field for the customerId Key.

    5. Click Send.

      A successful response returns a Status: 200 OK message and a response Body that looks as follows:

    Close

  • In the following example, we get a one-time password (OTP) for a specific device​​ from Zscaler Client Connector by sending a GET request to the /getOtp endpoint.

    1. In the workspace where you added your collection, go to Collections.
    2. Click the OneAPI folder and then click the Zscaler Client Connector folder.
    3. Go to Get OTP > Get OTP for device. The /getOtp request appears on the right pane.
    4. On the Params tab, select the udid query parameter and enter the Unique Device Identifier value. Optionally, you can configure udid as a variable and reference it in the requests.

    5. Click Send.

      A successful response returns a Status: 200 OK message along with an OTP in the response Body.

    Close

  • In the following example, we get the list of available Cloud & Branch Connector groups by sending a GET request to the /ecgroup endpoint.

    1. In the workspace where you added your collection, go to Collections.
    2. Click the OneAPI folder and then click the Zscaler Cloud & Branch Connector folder.
    3. Go to the Cloud & Branch Connector Groups folder and select Cloud & Branch Connector Groups - Get All Groups and VMs. The /ecgroup request appears on the right pane.

    4. Click Send.

      A successful response returns a Status: 200 OK message along with the Cloud & Branch Connector groups in the response Body.

    Close

To access specific coding language scripts, go to the request for which you need the script and click the Code icon in the toolbar. Select the desired language from the drop-down menu.

Related Articles
Understanding OneAPIGetting StartedConfiguring the Postman REST API Client