Configuring the Postman REST API Client


Configuring the Postman REST API Client

Zscaler supports the Google Chrome app version and the standalone macOS, Windows, and Linux versions of the Postman REST API client.

If you already have Postman installed and configured, you can right-click on the following link to download the latest version of the cloud service API Postman collection file: APIaaS.postman_collection.json.

Authenticating a Session in Postman

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

  1. Log in to the Zscaler Admin Portal using your API admin credentials. To learn more, see Getting Started.
  2. Go to Administration > API Key Management.
  3. In the Organization API Key tab, copy the Key.
  4. In Postman, if you are using the:
  1. Go to Authenticate > Authenticate - Post.
  2. Click Pre-request Script.
  3. Replace yourapikey with the Key you copied in step 3.
    Adding API Key to /authenticateSession request
  4. Click Body.
  5. Replace the username and password with your API admin credentials.
    Adding API user information to /authenticateSession request in Postman
  6. Click the Interceptor icon and enable the extension.
    Enable Interceptor in Postman
  1. Click Send.
  1. Go to File > Settings.
  2. Under General, turn off SSL certificate verification.
  3. In the APIaaS collection you imported previously, go to Authentication > Authenticate - Post.
  4. Click Pre-request Script.
  5. Replace yourapikey with the Key you copied in step 3.
    Adding API Key to /authenticateSession request
  6. Click Body.
  7. Replace the username and password with your API admin credentials.
    Adding API user information to /authenticateSession request in Postman
  8. Click Send.

If your API key and admin credentials were set up properly, you will receive a Status 200 OK message, for example:
/authenticateSession Response - Status 200 OK

Making an API Call in Postman

Try making an API call using Postman. In the following example, we'll look up categories for a specified list of URLs using /urlLookup:

  1. Make sure that you can authenticate successfully.
  2. Go to URL categories > URL lookup.

In Postman, you can click on the request Body to see the list of URLs. You can only look up to 100 URLs maximum per request, and each URL cannot exceed 1024 characters.

  1. Click Send.

You should receive a Status 200 OK message and a response Body that looks like the following:

/urlLookup Response - 200 OK

If you are using the Chrome app version and you have the Postman Interceptor extension installed and enabled, you are also able to see the JSESSIONID within Cookies, for example:

Postman Interceptor Enabled - JSESSIONID in Cookie

By default, the session is terminated after 30 minutes and re-authentication is required. However, the time interval can be changed, from 5 minutes to 600 minutes (10 hours), within the Zscaler Admin Portal. So, be sure to keep your idle time to less than the configured Admin Portal session timeout.

  1. Go to the Chrome Web Store and add the Postman App to your browser.
    Postman Chrome App Install
  2. Add the Postman Interceptor Extension to your browser.
    Postman Interceptor Extension Install
  3. Go to your Chrome Apps page (chrome://apps) and launch Postman.
  4. In the window that appears, create an account and log in.
    Postman Log In Window
  5. Right-click on the following link and download the Postman collection file: APIaaS.postman_collection.json
  6. Click Import.
    Import Button in Postman Client
  7. Make sure Import File is selected, and drag and drop the APIaaS.postman_collection file into the window or click Choose Files.
    Choose File to Import in Postman

After the file is imported, a new folder, APIaaS 5.6, is displayed within Collections.

  1. Click the Environment options icon and select Manage Environments.
    Manage Environments Menu in Postman
  2. In the Manage Environments window, complete the following steps:
    1. Click Add.
    2. Type in a descriptive Environment Name (e.g., Zscaler Test Environment).
    3. For the Key, type in url.
    4. For the key Value, type in https://<Cloud_Name>/api/v1. Where, <Cloud_Name> is the cloud name provisioned for your organization by Zscaler (e.g., admin.zscalertwo.net). To learn more, see What is my cloud name?
    5. Click Add and close the window.
      Add Environment and URL Set Key-Value for API in Postman

You can then select this environment (e.g., Zscaler Test Environment) from the drop-down menu in the Builder window.
Select an Environment in Postman

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

For example purposes, the following instructions reference the Windows 64-bit version of the app.

  1. Install the app.
  2. After installation the login window appears, create an account and log in. 

Postman Log In Window

  1. Right-click on the following link and download the Postman collection file: APIaaS.postman_collection.json
  2. From the main window, click Import.
  3. Make sure Import File is selected, and drag and drop the APIaaS.postman_collection file into the window or click Choose Files.
    Choose File to Import in Postman

After the file is imported, a new folder, APIaaS 5.6, is displayed within Collections

  1. Click the Environment options icon and select Manage Environments.
    Manage Environments Menu in Postman

If you previously installed the Chrome app version of the client and created an account, your imported collections and saved environments are available upon login.

  1. In the Manage Environments window, complete the following steps:
    1. Click Add.
    2. Type in a descriptive Environment Name (e.g., Zscaler Test Environment).
    3. For the Key, type in url.
    4. For the key Value, type in https://<Cloud_Name>/api/v1. Where, <Cloud_Name> is the cloud name provisioned for your organization by Zscaler (e.g., admin.zscalertwo.net). To learn more, see What is my cloud name?
    5. Click Add and close the window.
      Add Environment and url Set Key-Value for API in Postman>

You can then select this environment (e.g., Zscaler Test Environment) from the drop-down menu in the Builder window.
Select an Environment in Postman