Get Started with VMDR OT APIs
This help is intended for application developers who use the Qualys VMDR OT API.
Qualys API Framework
Learn the basics about making API requests. The base URL depends on the platform where your Qualys account is located. The Qualys VMDR OT API uses the following framework:
Request URL
The URL for making API requests respects the following structure:
https://<baseurl>/<module>/<object>/<object_id>/<operation>
Refer to the following table for the field description.
| Field | Description |
|---|---|
| <baseurl> | The Qualys API server URL that you should use for API requests depends on the platform where your account is located. The base URL for Qualys US Platform 1 is: https:///gateway.qg1.apps.qualys.com |
| <module> | The API module. For the VMDR OT API, the module is: “ot”. |
| <object> | The module-specific object. |
| <object_id> | (Optional) The module-specific object ID, if appropriate. |
| <operation> | The request operation, such as count. |
Qualys API Gateway URL
The Qualys API URL you should use for API requests depends on the Qualys platform.
Click here to identify your Qualys platform and get the API URL
This documentation uses the API gateway URL for Qualys US Platform 1 (https://gateway.qg1.apps.qualys.com) in sample API requests. If you are on another platform, please replace this URL with the appropriate gateway URL for your account.
Introduction to VMDR OT API Paradigm
Get tips on using the Curl command-line tool to make API requests. Every API request must authenticate using a JSON Web Token (JWT) obtained from the Qualys Authentication API.
Authentication
You must authenticate to the Qualys Cloud Platform using Qualys account credentials (user name and password) and get the JSON Web Token (JWT) before you can start using the VMDR OT APIs. Use the Qualys Authentication API to get the JWT.
Example Authentication Curl Request:
API Request
curl -X POST
"https://<QualysBaseURL>/auth"
-H "Content-Type: application/x-www-form-urlencoded"
-d "username=value1&password=value2&token=true"
The following table explains the various components of this request:
| QualysBaseURL | It is the base URL for the Qualys API server where your account is located. The base URL for Qualys US Platform 1 is: https:///gateway.qg1.apps.qualys.com |
| value1 and value2 | value1 is the username and value 2 is the password of the user account for which you want to fetch Asset Management data. |
| token | It must be true. |
| Content-Type | It must be application/x-www-form-urlencoded. |
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 following sample shows a typical Curl request using the options mentioned and how they interact.
Curl Request
curl -X POST
"https://gateway.qg1.apps.qualys.com/auth"
-H "Content-Type: application/x-www-form-urlencoded"
-d "username=john_doe&password=john_doe&token=true"
Permissions
To make calls using the VMDR OT API, you must have the VMDR OT.API.ACCESS permission.
To access all the data, you need to have both UI and API permissions.
API Rate Limits
The Qualys API enforces limits on the API calls a customer can make based on their subscription settings. The limits apply to using all Qualys APIs except the “auth” API (JWT Token Generation API). Default API control settings are provided by the service. Note these settings may be customized per subscription by Qualys Support. The rate count and period are calculated dynamically each time an API call is received. The rate period represents a rolling window when API calls are counted.
API Controls Definition
- X-RateLimit-Remaining: This indicates the total API calls remaining in the current rate limit window.
- X-RateLimit-ToWait-Sec: This time indicates the wait time for the rate limit to be reset. The customer has to wait for that time to execute the next API calls.
- X-RateLimit-Window-Sec: This value indicates the total time window assigned for the APIs to be executed.
- X-RateLimit-Limit: This indicates the max number of API calls that can be executed in that particular rate limit window.
Curl Request
curl -X GET -H "Accept: */*" -H "Authorization: Bearer <JWT Token>" -H
"Content-Type: application/json" -i
"https://gateway.qg1.apps.qualys.com/ot/v1/host/list"
Note: Provide "-i" in the curl request, as shown in the example, returns the response headers, including the rate limit related parameters.
After executing a curl request, check the following parameters in response headers to check the rate-limit status:
X-RateLimit-Remaining: 0
X-RateLimit-ToWait-Sec: 300
X-RateLimit-Window-Sec: 3600
X-RateLimit-Limit: 300
Sample HTTP Response Headers
Sample 1: Normal API call (API call not blocked)
HTTP/1.1 200 OK
transfer-encoding: chunked
X-RateLimit-Remaining: 290
X-RateLimit-Window-Sec: 3600
X-RateLimit-Limit: 300
count: 19788
vary: accept-encoding
Content-Type: application/json
Date: Mon, 06 Feb 2023 08:18:01 GMT
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
Sample 2: API Call Blocked - Rate Limit exceeded
HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-ToWait-Sec: 2050
X-RateLimit-Window-Sec: 3600
X-RateLimit-Limit: 300
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
content-length: 0
User Scoping for APIs
The user will get a response of the assets as per scope using list APIs. Typically Manager user has access to more assets than the reader user. So, the Reader user won’t be able to get responses for the APIs requested for unauthorized assets.
For example:
If a Manager user has access to 100 assets: List API will show details of all these 100 assets. Now, consider that the Manager user creates a ‘Reader’ sub-user and assigns only 50 assets to this user, and when Reader executes APIs, the response will contain data of only 50 assets and not all 100 assets.
API Versioning
We have implemented API versioning, a strategic change that empowers our customers with greater control, better stability, and smoother integration processes.
Benefits of API versioning
- Extended testing window: Under the new strategy, customers benefit from a more extended time window than the current 30-day period to experiment with new APIs, allowing for thorough testing and integration, ensuring that new functionalities can be seamlessly incorporated into your existing systems.
- Dual API access: To facilitate a smooth transition and minimize disruptions, customers have access to both the new and old versions of an API concurrently for conducting comprehensive tests against the new API while maintaining the production environment with the old API. This reduces the risk of integration issues and ensures that customers can confidently and systematically adopt new features.
- Enhanced agility for Qualys: This new strategy empowers Qualys with increased agility in API releases. By streamlining the versioning process and providing clear frameworks for updates and EOS, we can rapidly adapt to changing technological landscapes and customer needs.
To ensure continued support and access to the latest features, we encourage all customers using the endpoints listed here to upgrade to the latest version of the API endpoints within the specified timelines. This will help you avoid potential disruptions and ensure alignment with ongoing enhancements from Qualys.
To support your understanding, definitions of key terms such as End-of-Support(EOS) and End-of-life (EOL) are also included, explaining the lifecycle of each endpoint.
End-of-Support (EOS):
End-of-Support for an API version signifies the point at which Qualys will no longer actively maintain or enhance that specific version. While the API may continue to function, it will not receive new features, performance improvements, or security updates. This phase is intended to provide a grace period for API consumers to migrate to newer versions.
Implications of End-of-Support
- No New Features: The API version will not receive any further functional enhancements or new capabilities.
- Limited Bug Fixes: Critical security vulnerabilities may be addressed on a case-by-case basis, but general bug fixes for non-critical issues will stop.
- No Performance Improvements: Optimization efforts focus solely on newer API versions.
- Reduced Support Channels: Technical support for issues related to this specific API version may become limited, and users are strongly recommended to upgrade.
- No Guarantees of Reliability: While the API may remain operational, Qualys offers no guarantees regarding its continued reliability beyond the EOS date.
End-of-Life (EOL)
End-of-Life for an API version is the final stage where the API version is officially retired and will be completely decommissioned. After the EOL date, the API will no longer be available, and any calls to it will result in errors. This marks the complete discontinuation of service for that specific API version.
Implications of End-of-Life
- API Decommissioning: The API endpoint for this version is shut down and will no longer accept requests.
- Complete Service Stoppage: All functionalities provided by this API version will cease to exist.
- Error Responses: Any attempt to call the EOL API results in HTTP error codes, such as 404 Not Found or 410 Gone, or similar error messages.
- No Support: All forms of support, documentation, and resources related to this API version will be discontinued.
Get API Notifications
Subscribe to our API Notifications RSS Feeds for announcements and the latest news.