Getting Started with TotalCloud APIs

Many TotalCloud features are available through REST APIs. You can use tools like Postman to access the REST APIs we support.

Qualys Platforms

This document uses the following structure for sample API requests.

https://<QualysBaseURL>/cloudview-api/rest/v1/

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

The Qualys Base 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 Platform URL.

For example, if your account is on US Platform 1

https://qualysguard.qualys.com/cloudview-api/rest/v1/ 

Do I need to Authenticate?

Authentication to the Qualys Cloud Platform is necessary before you try the APIs.

TotalCloud offers three methods of authentication.

Basic Authentication

You can simply click Authorize and provide the username and password. You can now use the APIs!

Sample API Request to execute an API using Basic AuthenticationSample API Request to execute an API using Basic Authentication

curl -k -X POST -u <username>:<password> "https: //<QualysBaseURL>/cloudview-api/rest/v1/report/assessment/create"
  

Sample API Request to Execute API Using the above JWT Token and it's sample responseSample API Request to Execute API Using the above JWT Token and it's sample response

curl -k -X POST -u <username>:<password> "https: //<QualysBaseURL>/cloudview-api/rest/v1/report/assessment/create"

    {
    "reportName": "AWS Assessment Report",
    "description": "",
    "cloudType": "AWS",
    "query": "",
    "startDate": "2024-12-03T00:12:53Z",
    "endDate": "2024-12-10T18:53:s53Z",
    "executionType": "RUN_TIME",
    "policyIds": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
    ],
    "tagIds": [  
    ],
    "connectorIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        
    ],
    "format": "csv",
    "iacResourceResults": [  ]
}

Qualys Gateway Service Token-based Authentication

Qualys API Gateway service provides enhanced security with temporary access tokens. You can provide the limited-time Bearer token when executing your API call.

Sample API Request to execute an API using Gateway AuthenticationSample API Request to execute an API using Gateway Authentication

curl --location 'https://gateway.<platform_url>.qualys.com/cloudview-api/rest/v1/aws/connectors?pageNo=0&pageSize=50' \
--header 'accept: */*' \
--header 'Authorization: Bearer <Bearer Token>' \
--data ''
  

Sample API Request to Execute API Using the above JWT Token and it's sample responseSample API Request to Execute API Using the above JWT Token and it's sample response

    curl--location '<qualys_gateway_url>/cloudview-api/rest/v2/report/assessment/create'
--header 'Authorization: Bearer <access_token from above response>'

    {
    "reportName": "AWS Assessment Report",
    "description": "",
    "cloudType": "AWS",
    "query": "",
    "startDate": "2024-12-03T00:12:53Z",
    "endDate": "2024-12-10T18:53:s53Z",
    "executionType": "RUN_TIME",
    "policyIds": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
    ],
    "tagIds": [  
    ],
    "connectorIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        
    ],
    "format": "csv",
    "iacResourceResults": [  ]
}

OIDC Authentication

If you have enabled Open ID Connect Authentication for your account, you can authenticate yourself by generating a JWT token. This eliminates the need to provide the username and password for API calls.

This feature is not available by default. Contact Qualys support to enable it for your subscription. You must follow the onboarding process. This feature requires IdP.

Prerequsites

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 (usuallyin .pem or .cer files).

• IdP Name

  The name of the Identity Provider (IdP) being configured. This can be a customname 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. Upto 3 certificates can be provided. The certificate must be in X.509 format (usuallyin .pem or .cer files).

Onboarding Process

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

1. Contact Qualys Support (www.qualys.com/support) to request OpenID Connect API authentication activation for your subscription. A CRM ticket is automatically created and is used as a reference and tracking for all discussions concerning the activation.
2. Qualys Support replies to the ticket to share and request the required technical information used to enable OIDC. See the Prerequisites for the details.
3. Upon receipt of the response, Qualys enables OpenID Connect API authentication support. This process takes approximately one week to complete.

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 must first generate the JWT token and then use that token to execute the Qualys APIs. The following subsections provide API request and response samples for generating a JWT token and executing APIs using this token.

Sample API Request to Generate JWT Token for API Authentication and it's sample responseSample API Request to Generate JWT Token for API Authentication and it's sample response

    curl --location '
https://qualys.oktapreview.com/oauth2/aus27sviwo8jbrP4T0h8/v1/token'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'grant_type=password' 
--data-urlencode 'username=jdoe@qualysit.com' 
--data-urlencode 'password= ' 
--data-urlencode 'client_id=0oa27l586h672nMy90h8' 
--data-urlencode 'scope=openid profile'

    {
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": " ",
  "scope": "openid profile",
  "id_token": " "
}

Sample API Request to Execute API Using the above JWT Token and it's sample responseSample API Request to Execute API Using the above JWT Token and it's sample response

    curl--location '<qualys_gateway_url>/cloudview-api/rest/v2/report/assessment/create'
--header 'Authorization: Bearer <access_token from above response>'

    {
    "reportName": "AWS Assessment Report",
    "description": "",
    "cloudType": "AWS",
    "query": "",
    "startDate": "2024-12-03T00:12:53Z",
    "endDate": "2024-12-10T18:53:s53Z",
    "executionType": "RUN_TIME",
    "policyIds": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
    ],
    "tagIds": [  
    ],
    "connectorIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        
    ],
    "format": "csv",
    "iacResourceResults": [  ]
}