Get Started With VMPC API

VM, PC, SCA

Authentication to your Qualys account with valid Qualys credentials is required for making Qualys API requests to the Qualys API servers. Learn more

We recommend you join our Community and subscribe to our API Notifications RSS Feeds for announcements and discussions.

https://community.qualys.com/community/developer/notifications-api

The Qualys API URL you should use for API requests depends on the Qualys platform where your account is located.  

Click here to identify your Qualys platform and get the API URL

This documentation uses the API server URL for Qualys US Platform 1 (https://qualysapi.qualys.com) in sample API requests. If you're on another platform, please replace this URL with the appropriate server URL for your account.

Authentication to your Qualys account with valid Qualys credentials is required for making Qualys API requests to the Qualys API servers.

Basic Authentication

Using this method, Qualys account credentials are transmitted using the “Basic Authentication Scheme” over HTTPS for each API call. For information, see the “Basic Authentication Scheme” section of RFC #2617:

http://www.faqs.org/rfcs/rfc2617.html

The exact method of implementing authentication will vary according to which programming language is used.

Sample Request

curl -H "X-Requested-With: Curl Sample" -u "acme_ab12:passwd" "https://<qualys_base_url>/api/2.0/fo/asset/host/?action=list"

The "X-Requested-With" header parameter must be included in all API v2 calls using basic HTTP authentication and session based authentication. Specifying the required “X-Requested-With” parameter helps to protect Qualys API users from cross-site request forgery (CSRF) attacks.

Session Based Authentication

Using this method, the user makes a sequence of API requests. APIs with request URL containing /2.0/ support session based authentication.

Step 1 - Make session login request

Use the Qualys API session resource to make a login request. Upon success, the request returns a session ID in the Set-Cookie HTTP header. The exact method of implementing authentication will vary according to which programming language is used.

Sample Request

curl -H "X-Requested-With: Curl Sample" -D headers -d "action=login&username=acme_ab12&password=passwd" "https://<qualys_base_url>/api/2.0/fo/session/"

Step 2 - Make resource requests

Use the API resources to make API requests (2.0 must be in request URL), as described in this user guide, and include the session ID in the cookie header for each request. You’ll notice the session cookie (QualysSession) was extracted from the “headers” file contents returned from the session login API call (Step 1 above).

Sample Resource Request

curl -H "X-Requested-With: Curl Sample" -b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api; secure" -d "action=list" "https://<qualys_base_url>/api/2.0/fo/report/"

Step 3 - Make session logout request

Once logged in to Qualys you can make multiple API requests. Use the Qualys API session resource to logout of the current session. Logging out of the session closes the open session and ensures secure, ongoing access to your account. Access may be denied if a user makes too many session login requests without closing sessions properly:

Sample Logout Request

curl -H "X-Requested-With: Curl Sample" -b "QualysSession=10b8eb6d4553b4d1ecb860c2b3c247d4; path=/api; secure" -d "action=logout" "https://<qualys_base_url>/api/2.0/fo/session/"

Qualys Cloud Platform enforces limits on the API calls subscription users can make. The limits apply to the use of all APIs, except “session” V2 API (session login/logout).

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.

There’s 2 controls defined per subscription:

- Concurrency Limit per Subscription (per API). The maximum number of API calls allowed within the subscription during the configured rate limit period (as per service level).

- Rate Limit per Subscription (per API). The period of time that defines a window when API calls are counted within the subscription for each API. The window starts from the moment each API call is received by the service and extends backwards 1 hour or 1 day. Individual rate and count settings are applied (as per service level).

Click here to learn more about the controls and settings per service level.

How it works - Qualys checks the concurrency limit and rate limit each time an API request is received. In a case where an API call is received and our service determines a limit has been exceeded, the API call is blocked and an error is returned (the concurrency limit error takes precedence).

Your subscription’s API usage and quota information is exposed in the HTTP response headers generated by Qualys APIs (all APIs except "session" V2 API).

The HTTP status code "OK" (example: "HTTP/1.1 200 OK") is returned in the header for normal (not blocked) API calls. The HTTP status code "Conflict" (example: "HTTP/1.1 409 Conflict") is returned for API calls that were blocked.