UpGuard API
      Back to home
      1. UpGuard Knowledge Base
      2. UpGuard API

      How to make API calls to UpGuard using Postman

      Postman is a third-party application for making API calls. You can make calls to UpGuard using Postman.

      Written by Caitlin Postal

       

      You can always work directly within the UpGuard platform, but there are some tasks that you might wish to complete by making API calls. While you can make command-line requests or write scripts to use our API, you can also use third-party tools like Postman to streamline the process. While there are a variety of third-party tools that you can use, Postman integrates well with the UpGuard API and offers a free account level.

      In this tutorial, you will use Postman to make a sample API call to UpGuard. You will first set up your Postman environment with the UpGuard API specs and your authentication token, then you will use Postman to make a sample call to retrieve information from your UpGuard account.

      Prerequisites

      To complete the tasks in this guide, you will need the following:

      Integrating the UpGuard API with Postman

      In this section, you will upload UpGuard's API specs and your authentication key to Postman so that you can begin making API calls from Postman.

      First, download the UpGuard API Specification JSON file, which you can get with the Download button at the top of the UpGuard API docs site. The file will be named swagger.json, but you can rename it if you choose. Postman will use this file to communicate with UpGuard's API.

      Next, open Postman. You can use either the browser-based application or the desktop client. This tutorial will use the desktop client. Follow Postman's guide to create a new workspace or use an existing workspace. This tutorial uses a workspace named My Workspace.

      Select the Import button and upload the swagger.json file that you downloaded from UpGuard.

      You will have the option to create a collection that will group all the API calls from this file. To use this collection of requests, you will need to supply an authentication token or API key, following the recommended practices for securing API keys in Postman. Retrieve the API key that you generated in the prerequisites, or create a new one by following our article on How to authenticate with your UpGuard API key .

      Next, you will create an environment to hold your API key as a secure variable within Postman. Select Environments and then use the Create Environment option. Name it as you choose. This tutorial uses the name UpGuard.

      You'll now add a variable for your API key. In the Variable section of the table, add apiKey as the variable name. The variable name is case-sensitive. Then, add your UpGuard API key to both the Initial value and Current value sections where the screencapture reads your_api_key.

      Press Save.

      You'll now connect this variable to the environment you created using the environments dropdown in the upper right. By default, the variable is saved to No Environment. Select your named environment from the dropdown menu (this tutorial uses an environment named UpGuard).

      Setting the environment for this variable ensures that the authorization header for your API collection will be automatically generated with the authorization you have provided.

      Once you have saved your UpGuard API token as a variable and connected the key variable to your UpGuard collection, you can run API calls to your UpGuard account. In the next section, you'll run a sample call from Postman.

      Running an API call from Postman to UpGuard

      Now that you have set up your Postman instance, you can run a sample API call. In this tutorial, you will get a list of active risks for your account, but you can modify this approach for any API call with UpGuard.

      In Postman, open the collection for the UpGuard API.

      Navigate through the nested API calls to identify the relevant dropdown selection for the API call you wish to make. For this section, select risks and then the GET request named Get a list of active risks for your account.

      For this type of request, you can optionally include the minimum severity and any metadata for these risks. All the query parameters will return by default. To exclude this information from the response, uncheck the option for the key. For this tutorial, leave both options selected.

      Then press Send to send the request. The response will return in the Body section of the Postman client.

      The bar will include the response code, how long the call took, and the size of the response. With this example, the call was successful (status code 200). It took 1207 ms and returned 31.17 KB of data.

      You can review the output in the Body tab. You can select from options for the human-readable Pretty output, the monospaced Raw output with no spacing for readability, or the Preview text version of the monospaced raw output. Postman also offers a Postbot visualization option that has not been tested in this guide.

      You can also select the file output type. JSON will load by default, or you can select XML, HTML, or Text.

      If you would like to generate a script that you can use to run the same call, select the </> icon on the right navigation menu to open a Code snippet panel.

      The CURL script will load by default. Use the dropdown menu to select another option, such as Python - Requests or Go - Native, that will load a new script.

      The script will then load in the Code snippet panel. This example displays the Python - Requests script.

      This script will inherit the API variable you saved in Postman and whichever query parameters you selected.

      Note: If you intend to save this script and run it from your local machine, you can save your API key in a .env file in the root directory of your Python environment and call that file within the script using a package such as , which will ensure that your API key is not stored in the script. We have not evaluated the security of external packages like python-dotenv, and you should consult with your security team regarding the introduction of any new tooling.

      If you would like to compare this process to a command-line experience, you can read our article on How to retrieve risks detected for your account using the UpGuard API.

      Further reading

      You can use this method to run API calls at any time. While this section focused on one type of API call, you can select any of the options available in the UpGuard API specifications.

      UpGuard provides additional guides for making API calls directly from the command line. You can follow these guides from your terminal, or you can use Postman to make the same kinds of calls: