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>/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 then 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:

Option ID Example

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:

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 web application.

Integration Option Permissions

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

admin-only	user-can-edit	final permission
true	false	Lock and hide option for all users
true	true	Invalid combination
false	false	Lock and show option for all users
false	true	User provides option value

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://pp-dev.corp.polarity.io/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>/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. If you need to update multiple options for multiple integrations you must make a PATCH request per integration.