Introduction to Global AssetView API Paradigm

This topic helps to understand Global AssetView paradigm.

Authentication

You must authenticate to the Qualys Enterprise TruRisk™ Platform using Qualys account credentials (user name and password) and get the JSON Web Token (JWT) before you can start using the Global AssetView APIs. Use the Qualys Authentication API to get the JWT.

For example,

curl -X POST https://gateway.qg1.apps.qualys.com/auth -d
"username=value1&password=passwordValue&token=true" -H "Content-Type: application/x-www-form-urlencoded"      

where gateway.qg1.apps.qualys.com is the base URL to the Qualys API server where your account is located.

• username and password are the credentials of the user account for which you want to fetch Global AssetView data
• token should be true
• Content-Type should be "application/x-www-form-urlencoded"

The Authentication API returns a JSON Web Token (JWT) which you can use for authentication during Global AssetView calls. The token expires in 4 hours. You must regenerate the token to continue using the Global AssetView API.

Using Curl

Curl is a multi-platform command-line tool used to transfer data using multiple protocols. This tool is supported on many systems, including Windows, Unix, Linux and Mac. In this document Curl is used in the examples to build Qualys API requests using the HTTP over SSL (https) protocol, which is required.

Want to learn more? Visit  https://curl.haxx.se/

The following Curl options are used according to different situations:

The sample below shows a typical Curl request using the options mentioned above and how they interact with each other.

curl -X POST "https://gateway.qg1.apps.qualys.com/am/v1/assets" -H "Authorization: Bearer <token>"      

Limit Your Results

Use the optional fields parameter for any API request to limit the amount of information returned in the results. Simply specify the fields you want to include or exclude in the output, and all other information will be filtered out (excluded). Multiple fields are comma-separated.

When includeFields or excludeFields are specified, the response is filtered as follows:

• includeFields: Only the specified fields are returned with values. All other fields are returned as null.
• excludeFields: All fields are returned with values except the specified fields, which are returned as null.

Sample Limit ResultsSample Limit Results

curl -X POST -H "Accept: */*" -H "Authorization: <JWT Token>" -H "Content-Type: application/json" -i "<qualys_base_url>/am/v1/assets/host/list?pageSize=100&includeFields=operatingSystem,hardware"      

Supported Fields

You can include the following fields to limit your results:

Fetching Source Details for an Asset

To fetch source details for an asset, include `inventory` in the `includeFields` parameter. When specified, the API returns source information in two places within the response:

• `inventoryListData.inventory`
  Displays the complete list of sources that discovered the asset.
• `inventory`
  Displays the asset source data.

Example:

{
  "inventory": {
    "source": "QAGENT",
    "created": 1728017705000,
    "lastUpdated": 1767028258000
  },
  "inventoryListData": {
    "inventory": [
      {
        "source": "CAPS",
        "created": 1738673171000,
        "lastUpdated": 1738715633000
      },
      {
        "source": "Cloud Agent",
        "created": 1728017705000,
        "lastUpdated": 1767028258000
      }
    ]
  }
}

In this example:

The `inventory` and `activity` fields show the asset source data. To view the list of all source details for the asset, we recommend referring to the `inventoryListData.inventory` field in the response.