Troubleshooting Qualys API

Document created by Spencer Brown Employee on Dec 21, 2019Last modified by Spencer Brown Employee on Mar 26, 2020
Version 15Show Document
  • View in full screen mode

This document is intended to help customers isolate API issues and provide sufficient evidence to Qualys Support for quick resolution.  The API examples are from the Host List Detection; however, other API endpoints can use the same methodology.


When encountering API issues, follow the steps below until remediation.

Basic Steps

1) Validate API access has been granted to user 


Expected output without API access
<?xml version="1.0" encoding="UTF-8" ?>
        <TEXT>Bad Login/Password</TEXT>

2) Validate user has correct permissions. 

Qualys recommends using the "Manager" role as this gives permissions to pull all assets

3) Validate server and gateway URL for user account

Use the platform identifier in your Qualys username to determine your Qualys platform: Qualys Platform Identification | Qualys, Inc. 


Expected output using incorrect server URL
<?xml version="1.0" encoding="UTF-8" ?>
        <TEXT>Bad Login/Password</TEXT>


Isolation Steps 

1) Attempt API call using Postman or curl


  • Attempting with Postman

   More about using Postman with Qualys APIs: Quick Start Guide for the Qualys API (Postman Edition)



  • Attempting with curl


Sample curl command

curl -u "username:password" -H "X-Requested-With: curl" ""


2) Attempt API call off of the corporate network

  • Corporate networks can additional variables such as proxy and latency


If API errors or timeouts are intermittent and are not reproducible, Qualys recommends adding error handling and retry logic to your automation


Issue Still Persists

Contact customer via How to Contact Qualys Support and attach the following to case captured via Postman or Curl:

  1. Full API call with parameters from Isolation Steps
  2. Full XML output



Generate collection file and public link





NOTE: before sharing, please remove authentication to not expose credentials


More about sharing collections


Run curl command with verbose flag for additional logging and output to text file


Curl command with -v flag

curl -v -u "username:password" -H "X-Requested-With: curl" "" > /path/to/file


Curl output
* Trying
* Connected to ( port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
* CAfile: /etc/ssl/cert.pem
CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* ALPN, server accepted to use http/1.1
* Server certificate:
* subject: C=US; ST=California; L=Foster City; O=Qualys, Inc.; OU=Production;
* start date: Jul 30 00:00:00 2019 GMT
* expire date: Jul 30 12:00:00 2020 GMT
* subjectAltName: host "" matched cert's ""
* issuer: C=US; O=DigiCert Inc; CN=DigiCert SHA2 Secure Server CA
* SSL certificate verify ok.
* Server auth using Basic with user 'quays2kb58'
> GET /api/2.0/fo/asset/host/vm/detection/?action=list HTTP/1.1
> Host:
> Authorization: Basic cXVheXMya2I1ODpDVjA=
> User-Agent: curl/7.64.1
> Accept: */*
> X-Requested-With: curl
< HTTP/1.1 401 Unauthorized
< Date: Sat, 21 Dec 2019 19:51:00 GMT
< Server: Qualys
< Strict-Transport-Security: max-age=63072000;
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< Strict-Transport-Security: max-age=31536000; includeSubDomains
< Transfer-Encoding: chunked
< Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<TEXT>Bad Login/Password</TEXT>
* Connection #0 to host left intact
* Closing connection 0



More about roles: User Roles Comparison (Vulnerability Management)