Qualys Cloud Agent Application Release 2.5 API

November 06, 2025

Before understanding the API release highlights, learn more about the API server URL to be used in your API requests by referring to the Know Your Qualys API Server URL section. For this API Release Notes, <qualys_base_url> is mentioned in the sample API requests. Replace this placeholder value with the appropriate Qualys Gateway URLs.

New Activation Key APIs

We are introducing the following new APIs for Activation Key management and search.

Get Activation Key Details API
Search Activation Key API
Create Activation Key API
Update Activation Key API
Enable/Disable Activation Key API
Delete Activation Key API

All the newly introduced Activation Key APIs can be accessed only with the Qualys Gateway URLs. To learn more about using API Gateway URL, refer Cloud Agent API Guide or API URLs section at Identify your Qualys Platform.

New API: Get Activation Key Details

New or Updated API	New
API Endpoint	/caui/v1/activation-keys/manage/<id>
Method	GET
DTD or XSD Changes	NA

Use this API to fetch the activation key details. To get details of an activation key, provide the Activation Key ID in the API request.

Permissions required: Access Permissions — API Access, and CA Activation Key Permission — View Activation Key.

Sample - Fetch Activation Key DetailsSample - Fetch Activation Key Details

API Request

 curl --location --request GET '<qualys_base_url>/caui/v1/activation-keys/manage/1234567' \ 
 --header 'Authorization: Bearer <JWT Token>' \

API Response

 
    {
        "id": 123456,
        "title": “Activation_key_title_01”,
        "activationKey": "123456-1a2b-1a2b-1a2b-12ab12b2b123",
        "networkId": 0,
        "countUsed": 0,
        "countPurchased": 0,
        "datePurchased": "2025-09-08T18:40:11",
        "firstName": "John",
        "lastName": "Doe",
        "userName": "<username>",
        "keyType": "Unlimited",
        "expireDate": null,
        "isDisabled": false,
        "licenses": [
          "VM",
          "PA"
        ],
        "tags": [],
        "applyToExistingAgents": false
      }

New API: Search Activation Keys

New or Updated API	New
API Endpoint	/caui/v1/activation-keys/manage
Method	POST
DTD or XSD Changes	NA

Use this API to search the activation keys. You can use the query parameter in the API request to fetch the required activation keys.

Pagination - A maximum of 10 activation key records are displayed by default. To specify the number of results to be generated by the API, use the limit parameter.

Permissions required: Access Permissions — API Access, and CA Activation Key Permission, and View Activation Key.

Input ParametersInput Parameters

Parameter	Mandatory/Optional	Data type	Description
limit	Optional	Integer	Use this parameter to specify the maximum number of activation key records to be displayed in the API response. Default value: 10 activation key records.
sortOrder	Optional	String	Use this parameter to define the sorting order for the activation key records in the API response. Valid values: ASC, DSC
orderBy	Optional	String	Use this parameter to define the sorting criteria for the activation key records in the API response. Valid values: TITLE, ACTIVATION_KEY, AGENTS, CREATED_ON, STATUS, EXPIRES
query	Optional	String	Use this parameter to define the search criteria for the activation key records to be displayed in the API response. For example, to search all the disabled activation keys in the user account, use the following search query. `"query": "activationKey.isDisabled: true"`

Sample - Search Activation KeysSample - Search Activation Keys

API Request

 
      curl --location --request POST '<qualys_base_url> /caui/v1/activation-keys/manage’
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <JWT Token>' \

API Request Body

 --data ''
      {
         "limit": 200,  
         "sortOrder": "ASC",
         "orderBy": "TITLE",
         "query": "activationKey.isDisabled:false"
         }

API Response

 
      {
         "pageSize": 5,
         "totalCount": 745,
         "noOfPages": 149,
         "content": [
         {
            "id": 12345678,
            "title": "activation_key_title_1",
            "activationKey": "123456-1a2b-1a2b-1a2b-12ab12b2b123",
            "countUsed": 0,
            "countPurchased": 0,
            "datePurchased": "2025-01-09T18:01:02",
            "firstName": "John",
            "lastName": "Doe",
            "userName": "<username01>",
            "keyType": "Unlimited",
            "isDisabled": false,
            "expireDate": null,
            "licenses": [
               "PM",
               "VM",
               "FIM",
               "PA",
               "EDR"
            ]
        },
        {
          "id": 23456789,
          "title": "activation_key_title_2",
          "activationKey": "123456-1a2b-1a2b-1a2b-12ab12b2b122",
          "countUsed": 0,
          "countPurchased": 0,
          "datePurchased": "2025-01-29T12:26:26",
          "firstName": "John",
          "lastName": "Doe",
          "userName": "<username01>",
          "keyType": "Unlimited",
          "isDisabled": false,
          "expireDate": null,
          "licenses": []
        },
        {
          "id": 34567891,
          "title": "activation_key_title3",
          "activationKey": "123456-1a2b-1a2b-1a2b-12ab12b2b124",
          "countUsed": 0,
          "countPurchased": 0,
          "datePurchased": "2025-01-29T09:41:04",
          "firstName": "John",
          "lastName": "Doe",
          "userName": "<username01>",
          "keyType": "Unlimited",
          "isDisabled": false,
          "expireDate": null,
          "licenses": [
            "VM",
            "FIM",
            "EDR"
          ]
        },
        {
          "id": 456789123,
          "title": "activation_key_title4",
          "activationKey": "123456-1a2b-1a2b-1a2b-12ab12b2b124",
          "countUsed": 0,
          "countPurchased": 0,
          "datePurchased": "2025-01-29T09:46:07",
          "firstName": "John",
          "lastName": "Doe",
          "userName": "<username01>",
          "keyType": "Unlimited",
          "isDisabled": false,
          "expireDate": null,
          "licenses": []
        },
        {
          "id": 567891234,
          "title": "activation_key_title5",
          "activationKey": "123456-1a2b-1a2b-1a2b-12ab12b2b124",
          "countUsed": 0,
          "countPurchased": 0,
          "datePurchased": "2024-08-14T18:08:36",
          "firstName": "John",
          "lastName": "Doe",
          "userName": "username01",
          "keyType": "Unlimited",
          "isDisabled": false,
          "expireDate": null,
          "licenses": []
        }
      ]
    }

New API: Create Activation Key

New or Updated API	New
API Endpoint	/caui/v1/activation-keys/manage/activation-key
Method	POST
DTD or XSD Changes	NA

Use this API to create an activation key. While creating an activation key, you can specify the Qualys applications to be activated for associated Cloud Agents, Key Type, Expiry Date, and so on.

Permissions required: Access Permissions — API Access, and CA Activation Key Permission — Create Activation Key.

Input ParametersInput Parameters

Parameter	Mandatory/Optional	Data Type	Description
title	Optional	String	Enter the activation key title. If the field is not provided, a key with a blank title is created.
networkId	Optional	Integer	Enter the network ID for the key. The Cloud Agents installed with this key will use the specified network ID.
expireDate	Optional	Date	Enter the expiry date for the key in UTC/GMT format, i.e., YYYY-MM-DD. If the field is not provided, a key with no expiry date limit is created.
maxAgentsAllowed	Optional	Integer	Specify the number of agents allowed to be installed with this key. If the maximum agent count is not defined, the key can be used to install a maximum up to 1000000 Cloud Agents. Valid range: 1-1000000.
licenses	Optional	String	Provision one or more Qualys applications for the key. Valid values: VM, PC/PA, FIM, EDR, SCA, PM, CAPS, SwCA, MTG, ISL, and so on.
tags	Optional	Integer	Enter the tag IDs for this key. These tags will be assigned to the Cloud Agents installed with the key.

Sample - Create an Activation KeySample - Create an Activation Key

API request


    curl --location --request POST '<qualys_base_url> /caui/v1/activation-keys/manage/activation-key'
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <JWT Token>'

API Request Body

--data ''
    {
      "title": "Test Activation Key",
      "networkId": 123456,
      "expireDate": "2026-09-08",
      "maxAgentsAllowed": 100,
      "licenses": [
        "VM","PC","PM"
      ],
      "tags": [
        123456
      ]
    }

API Response


    {
      "id": 123456,
      "title": “Test Activation Key”,
      "activationKey": "12ba12bc-effd-12e3-1234-12345ac12345",
      "networkId": 123456,
      "countUsed": 0,
      "countPurchased": 100,
      "datePurchased": "2025-09-08T19:43:45.378378608",
      "firstName": "John",
      "lastName": "Doe",
      "userName": "<username>",
      "keyType": "Count Time Limited",
    "expireDate": "2026-09-08"
      "isDisabled": false,
      "licenses": [
        "PM",
        "VM",
        "SCA"
      ],
      "tags": [],
      "applyToExistingAgents": false
    }

New API: Update Activation Key

New or Updated API	New
API Endpoint	/caui/v1/activation-keys/manage/activation-key/ <id>
Method	PATCH
DTD or XSD Changes	NA

Use this API to update the activation key configurations. Provide the activation key ID to specify the key to be updated.

Permissions required: Access Permissions — API Access, and CA Activation Key Permission — Edit Activation Key.

Input ParametersInput Parameters

Parameter	Mandatory/Optional	Data type	Description
title	Optional	String	Enter the activation key title. If the field is not provided, the key title remains unchanged.
networkId	Optional	Integer	Enter the network ID for the key. The Cloud Agents installed with this key will use the specified network. If the field is not provided, network for the key remains unchanged.
expireDate	Optional	Date	Enter the expiry date for the key in UTC/GMT format, i.e., YYYY-MM-DD. If the field is not provided, expiry date limit for the key remains unchanged.
removeExpireDate	Optional	Boolean	Use this parameter to remove the expiry date limit for the key. Valid values: true, false
maxAgentsAllowed	Optional	Integer	Specify the number of agents allowed to be installed with this key. The parameter value should be more than the number of Cloud Agents already installed with the key. If the field value is not used, the maximum count limit remains unchanged. Valid range: 1-1000000.
removeMaxAgentsAllowed	Optional	Boolean	Use this parameter to remove the maximum agent installation limit. Valid value: true, false
applyToExistingAgents	Optional	Boolean	Use this parameter to apply the updated activation key configuration to the Cloud Agents associated with this key. Valid values: true, false
addLicenses	Optional	String	Use this parameter to provision this key for new Qualys applications. If the field is not provided, the applications added for the activation key remain unchanged. Valid values: VM, PC/PA, FIM, EDR, SCA, PM, CAPS, SwCA, MTG, ISL, and so on.
removeLicenses	Optional	String	Use this parameter to remove the already provisioned Qualys applications for the key. If the field is not provided, the applications added for the activation key remain unchanged. Valid values: VM, PC/PA, FIM, EDR, SCA, PM, CAPS, SwCA, MTG, ISL, and so on.
addTags	Optional	Integer	Use this parameter to add new tags to the activation key. Specify the tags using the tag IDs. If the field is not provided, tags added to the key remain unchanged.
removeTags	Optional	Integer	Use this parameter to remove existing tags added to the activation key. Specify the tags using the tag IDs. If the field is not provided, tags added to the key remain unchanged.

Sample - Update Activation KeySample - Update Activation Key

API Request

 
    curl --location --request PATCH ' /caui/v1/activation-keys/manage/activation-key/123456’ 
    --header 'Content-Type: application/json' \ 
    --header 'Authorization: Bearer Token' \

API Request Body

 --data ''
  {   
     "title": "string", 
     "networkId": 123456,   
     "removeExpireDate": true,   
     "maxAgentsAllowed": 100,   
     "applyToExistingAgents": true,   
     "addLicenses": [     
        "PM"   
        ],   
     "removeLicenses": [     
        "SCA"   
        ],   
     "addTags": [     
        123456   
        ],   
     "removeTags": [     
        345678   
        ] 
     }

API Response

Successfully updated activation key

New API: Enable/Disable Activation Key

New or Updated API	New
API Endpoint	/caui/v1/activation-keys/manage/<id>
Method	PATCH
DTD or XSD Changes	NA

This is a common API for enabling or disabling an activation key. The API response depends on the activation key status as the time of API execution. Provide the Activation Key ID to specify the Activation Key to be enabled/disabled.

Permissions required: Access Permissions — API Access, and CA Activation Key Permission — Enable Activation Key/ Disable Activation Key.

Sample - Enable Activation KeySample - Enable Activation Key

API Request

 
  curl --location --request PATCH '<qualys_base_url> /caui/v1/activation-keys/manage/1819838
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <JWT Token>'

Ensure that Activation Key ID provided in API request refers to a disabled activation key. Providing the key ID of an enabled activation key will result in error.

API Response

 Successfully disabled activation key

The API response for this API depends on the activation key status. If the activation key is enabled before executing this API, the response will be Successfully disabled activation key and vice versa.

New API: Delete Activation Key

New or Updated API	New
API Endpoint	/caui/v1/activation-keys/manage/<id>
Method	DELETE
DTD or XSD Changes	NA

Use this API to delete an activation key using the key ID. The activation keys that has active agents associated with it, cannot be deleted. Provide the Activation Key ID in the API Request to specify the key that you want to delete.

Permissions required: Access Permissions — API Access, and CA Activation Key Permission — Delete Activation Key.

Sample - Delete an Activation KeySample - Delete an Activation Key

API Request

 
  curl --location --request DELETE '<qualys_base_url> /caui/v1/activation-keys/manage/123456
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <JWT Token>' \

API Response

 Successfully deleted activation key

Last updated: November, 2025