Get Started with ETM APIs
This help is intended for application developers who use the Qualys ETM APIs. We support asynchronous operations on APIs. ETM APIs are designed for asynchronous operations. You can request services and receive responses later, ensuring non-blocking execution.
Benefits of Asynchonous Operation
- Parallel Execution
Enhanced the execution capabilities to allow statements to run in parallel without interrupting the overall program flow.
- Performance Enhancements
Improvements in the asynchronous processing speed make it more suitable for CPU-intensive tasks that need to be executed simultaneously.
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 ETM API uses the following framework.
Request URLRequest 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 For documentation purposes, we use <qualys_base_url>. |
|
<module> |
The API module. For the ETM API, the module is: etm. |
|
<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 Enterprise TruRisk platform.
Click here to identify your Qualys platform and get the API URL
This documentation uses the API gateway URL for <qualys_base_url> in sample API requests. If you are on another platform, replace this URL with the appropriate gateway URL for your account.
Introduction to ETM 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.
AuthenticationAuthentication
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 Certificate View APIs. Use the Qualys Authentication API to get the JWT.
Example Authentication Curl Request:
API Request
curl -X POST
"<qualys_base_url>/auth" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "username=<value1>" --data-urlencode "password=<value2>" --data-urlencode "token=true&permissions=true"
The following table explains the various components of this request:
| qualys_base_url | 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 ETM data. |
| token | It must be true. |
| permissions | It must be true. |
| Content-Type | It must be application/x-www-form-urlencoded. |
Using CurlUsing 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 "<qualys_base_url>/auth" -H "Content-Type: application/x-www-form-urlencoded"
-d "username=john_doe&password=john_doe&token=true&permissions=true"
Permissions
To make calls using the ETM API, you must have API Access permission in your role.
- Navigate to the Administration module > Role Management > Edit Role > Role Details.
- In the Permissions tab, select API Access from Select how users would access this application section.
-
Select EnterpriseTruRisk Management from Modules.
-
Select ETM API Access from ETM Permissions and click Save.
For more details on role creation, refer to the Online Help of Administration module.
API Rate Limits
The Qualys API enforces limits on the API calls a customer can make based on their subscription settings. Default API control settings are provided by the service.
These settings may be customized per subscription by Qualys Support.
API controls are applied per subscription based on your subscription’s service level. Default settings are provided and these may be customized per subscription by Qualys Support.
Concurrency Limit per Subscription (per API): This is the maximum number of concurrent API calls allowed within the subscription for each API (as per service level).
Rate Limit per Subscription (per API): Individual rate and count settings are applied (as per service level).
Rate Limit Count per Subscription (per API): The maximum number of API calls allowed within the subscription during the configured rate limit period.
Rate Limit Period per Subscription (in seconds, per API): The period of time that defines a window when API calls are counted within the subscription for each API.
By default, you get Standard API service.
Service Level API Control
| Service Level | API Control |
|---|---|
| Standard API Service |
|
Get API Notifications
Subscribe to our API Notifications RSS Feeds for announcements and the latest news.
|
From our Community |