Integration Options

Updating Integration Options

Integration option values can be updated via a PATCH HTTP request to the integration-options endpoint.

PATCH https://<polarity.server.url>/api/integration-options
{
  "data": [
    {
      "id": "<INTEGRATION_ID>-<OPTION_KEY>",
      "type": "integration-option",
      "attributes": {
        "value": "<OPTION_VALUE>",
        "admin-only": true,
        "user-can-edit": false
      }
    }
  ]
}

Updating an option value requires knowing the ID of the integration option you want to update.  

The integration option ID is a compound ID constructed by joining the integration id, a dash, and the option key.

Option ID Format:

<INTEGRATION_ID>-<OPTION_KEY>

For example, if the integration ID is virustotal_node_18_1725278818 and the option key is apiKey then the option ID would be:

virustotal_node_18_1725278818-apiKey

The option key can be found by querying for the integration's attributes via the GET /api/integrations/<INTEGRATION_ID> endpoint.  For more information on this endpoint see the section on Retrieving Integration Information.

Alternatively, you can find the option key by viewing the integration's config/config.json file and looking for the key property under the options list.  As an example, here is what the VirusTotal option configuration looks like:

{
  "key": "apiKey",
  "name": "VirusTotal API Key",
  "description": "Your VirusTotal API Key",
  "default": "",
  "type": "password",
  "userCanEdit": true,
  "adminOnly": false
}

The key property specifies a value of apiKey which is the option key value used to construct the option id.

Integration Option Permissions

Each integration option has permissions associated with it that are set via the adminOnly and userCanEdit Boolean flags.  These flags correspond to the option permissions that each option have in the integration settings page via the Polarity Web Interface.

The following table shows how the two values map to the values displayed in the UI:

As an example, if you wanted to set VirusTotal so that the provided API key is locked and hidden (i.e., "Lock and hide option for all users"), you would send the following payload:

"attributes": {
  "value": "virustotal_node_18_1725278818-apiKey",
  "admin-only": true,
  "user-can-edit": false
}

The admin-only and user-can-edit attributes are optional and do not have to be provided if you do not want to change the option's permissions from their current values.

CURL

curl -v -X PATCH \
'https://<polarity.server.url>/api/integration-options' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
--data-binary @- <<EOF
{
  "data": [
    {
      "id": "<INTEGRATION_ID>-<OPTION_KEY>",
      "type": "integration-options",
      "attributes": {
        "value": "<OPTION_VALUE>",
        "admin-only": true,
        "user-can-edit": false
      }
    }
  ]
}
EOF

Python

import requests
import json

def update_integration_option(token, host, option_id, option_value):
    url = f'{host}/api/integration-options'

    payload = json.dumps({
      "data": [
        {
          "id": option_id,
          "type": "integration-options",
          "attributes": {
            "value": option_value,
            "admin-only": true,
            "user-can-edit": false
          }
        }
      ]
    })
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request("PATCH", url, headers=headers, data=payload)
    response.raise_for_status()

    return response.json()
    
update_result = update_integration_option(token, HOST, 'virustotal_3_7_4_node_18_63e5110da4_1697729362-apiKey', 'myapikey')  

You can update multiple options for the same integration at the same time by passing them into the data property of the payload.   For example, the following payload would update the apiKey and maxAge option for the AbuseIPDB integration with an integration ID of abuseipdb_3_3_4_node_18_71ff23754e_1725342515

PATCH https://<polarity.server.url>/api/integration-options
{
  "data": [
    {
      "id": "abuseipdb_3_3_4_node_18_71ff23754e_1725342515-maxAge",
      "type": "integration-option",
      "attributes": {
        "value": 180
      }
    },
    {
      "id": "abuseipdb_3_3_4_node_18_71ff23754e_1725342515-apiKey",
      "type": "integration-option",
      "attributes": {
        "value": "my_abuseipdb_api_key"
      }
    }    
  ]
}

While you can update multiple options per API call, you can only update a single integration when doing so.

If you need to update multiple options for multiple integrations, you must make a PATCH request for each integration.