Get Started With VM, PA/PC APIs

VM, PA/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/"

we have upgraded our API security by incorporating OpenID Connect for Qualys API authentication and authorization. When OpenID Connect API authentication is implemented, IdP is used for user authentication and JWT token generation for the Qualys API access.

Once you enable OpenID connect authentication, you can use either basic authentication or JWT token authentication while executing the Qualys APIs.

Key Highlights

• Seamless integration of OpenID Connect to enhance API authentication and authorization measures.
• Compatibility with current identity providers and authentication to facilitate a seamless integration experience.
• This authentication is supported by all Qualys APIs, /api/2.0/ and onward versions.
• Eliminates the need for users to provide a username and password. This streamlines Qualys API access by allowing users to use JWT tokens, bypassing the hassle associated with usernames and passwords.

-This feature is not available by default. Contact  Qualys support to enable it for your subscription. There is an onboarding process that needs to be followed. Refer to the Onboarding Process.

-This feature requires IdP.

Benefits

• Enhanced API security
  OpenID Connect (OIDC) uses tokens to establish a user's identity and grant access.
• Standardized access control
  OpenID Connect (OIDC) provides a standardized way to manage user identities and access control.
• Centralized Authentication
  By enabling IDP-initiated SSO, users can authenticate once through your organization’s Identity Provider (IDP) and gain access to all the necessary APIs without needing to log in again. This simplifies the user experience and reduces password fatigue, making access faster and more secure.
• Compliance and Security
  Helps to meet compliance requirements by ensuring that user authentication processes adhere to established security protocols like SAML and OIDC.

Prerequisites

In order to enable OpenID Connect API authentication support, technical information needs to be provided as listed below:

• IdP Name
  The name of the Identity Provider (IdP) being configured. This can be a custom name or provided by the customer. Example: "TestNameforIDP Qualys Internal"
• Entity ID
  The unique identifier for the customer’s IdP. Typically, this is a URN or URL that serves as the IdP’s primary identifier during OIDC communications. Example: "https://example.com/idp"
• Single Sign-On (SSO) URL
  The URL where authentication requests will be sent. This is the endpoint where users are redirected to authenticate with the customer’s IdP. Example: "https://example.com/login"
• Single Logout (SLO) URL (if applicable) 
  The URL for handling logout requests. If you support Single Logout, this endpoint will manage the termination of sessions both at the IdP and within Qualys. Example: "https://example.com/logout"
• SSO Exit URL (optional)
  The URL where users will be redirected after successful authentication.
• Certificates
  Public signing certificates for verifying the authenticity of SAML responses. Up to 3 certificates can be provided. The certificate must be in X.509 format (usually in .pem or .cer files).

Onboarding Process

To start using OpenID Connect API authentication, the following onboarding process must be completed:

1. Contact Qualys Support to request OpenID Connect API authentication activation for your subscription.
2. Qualys Support requests the necessary technical information to enable OIDC. See the Prerequisites for the details.
3. Upon receipt of the technical information, Qualys enables OpenID Connect API authentication support.

Use OpenID Connect API Authentication

Once the onboarding process is complete and the OpenID Connect API authentication is enabled, you can begin using it. To start using it, you first need to generate the JWT token and then use that token to execute the Qualys APIs.

Sample- Execute API Using JWT TokenSample- Execute API Using JWT Token

curl --location --request POST 'https:// <qualys_base_url>/api/2.0/fo/asset/ip/?action=add&enable_vm=1&ips=10.10.10.10&echo_request=1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer <JWT token value>'\
--header 'X-Requested-With: curl Autodemo' \
--header 'Accept: */*' \
--header 'Content-Length: 0'

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https:// <qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
    <REQUEST>
        <DATETIME>2024-11-06T07:32:58Z</DATETIME>
        <USER_LOGIN>mayur_aa</USER_LOGIN>
        <RESOURCE>https:// <qualys_base_url>/api/2.0/fo/asset/ip/</RESOURCE>
        <PARAM_LIST>
            <PARAM>
                <KEY>action</KEY>
                <VALUE>add</VALUE>
            </PARAM>
            <PARAM>
                <KEY>enable_vm</KEY>
                <VALUE>1</VALUE>
            </PARAM>
            <PARAM>
                <KEY>ips</KEY>
                <VALUE>10.10.10.10</VALUE>
            </PARAM>
            <PARAM>
                <KEY>echo_request</KEY>
                <VALUE>1</VALUE>
            </PARAM>
        </PARAM_LIST>
    </REQUEST>
    <RESPONSE>
        <DATETIME>2024-11-06T07:33:05Z</DATETIME>
        <TEXT>IPs successfully added to Vulnerability Management</TEXT>
    </RESPONSE>
</SIMPLE_RETURN>

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.