# Integration Options

## Updating Integration Options

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

{% code title="Request Path" %}

```
PATCH https://<POLARITY_SERVER>/api/integration-options
```

{% endcode %}

{% code title="" %}

```
{
  "data": [
    {
      "id": "<INTEGRATION_ID>-<OPTION_KEY>",
      "type": "integration-option",
      "attributes": {
        "value": "<OPTION_VALUE>",
        "admin-only": true,
        "user-can-edit": false
      }
    }
  ]
}
```

{% endcode %}

{% hint style="info" %}
Be sure to include the `Content-Type` header with a value of `application/vnd.api+json`
{% endhint %}

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.

{% code title="Option ID Format" %}

```
<INTEGRATION_ID>-<OPTION_KEY>
```

{% endcode %}

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

{% code title="Option ID Example" %}

```
virustotal_node_18_1725278818-apiKey
```

{% endcode %}

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:

{% content-ref url="" %}
[](https://docs.polarity.io/polarity-admin-guide-version-5/NgjzS0G79DnLnaNepozV/rest-api/integration-information)
{% endcontent-ref %}

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](https://github.com/polarityio/virustotal/blob/bfa1874d5907a115f093924ab5492cfa29c2c62c/config/config.json#L48) looks like:

```json
{
  "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.

<figure><img src="https://3987119652-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVpjwU8I9r4Ntr01KWXNm%2Fuploads%2FpivvTvlYyjCLcnDaZX97%2Fimage.png?alt=media&#x26;token=2c960028-db8a-4842-ae5c-a62b54cfd025" alt=""><figcaption><p>Integration Option Permissions</p></figcaption></figure>

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

<table><thead><tr><th width="163">admin-only</th><th width="138">user-can-edit</th><th>final permission</th></tr></thead><tbody><tr><td>true</td><td>false</td><td>Lock and hide option for all users</td></tr><tr><td>true</td><td>true</td><td><em>Invalid combination</em></td></tr><tr><td>false</td><td>false</td><td>Lock and show option for all users</td></tr><tr><td>false</td><td>true</td><td>User provides option value</td></tr></tbody></table>

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
}
```

{% hint style="info" %}
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.
{% endhint %}

{% tabs %}
{% tab title="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
```

{% endtab %}

{% tab title="python" %}

```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')  
```

{% endtab %}
{% endtabs %}

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"
      }
    }    
  ]
}
```

{% hint style="info" %}
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.
{% endhint %}