Updating Integration Permissions

Adding Permissions

Integration permissions can be updated via a POST request to the integration's permissions endpoint.  

The endpoint will return a 204 HTTP status code with no content on success.

POST https://<polarity.server.url>/api/integrations/<INTEGRATION_ID>/permissions
{
  "data": [
    {
      "type": "permissions",
      "attributes": {
        "permissions": [
          "read",
          "admin"
        ]
      },
      "relationships": {
        "group": {
          "data": {
            "type": "groups",
            "id": "<GROUP_ID>"
          }
        },
        "integration": {
          "data": {
            "type": "integrations",
            "id": "<INTEGRATION_ID>"
          }
        }
      }
    }
  ]
}

Permission Values

Valid permission values are read and admin.  

The read permission gives a user access to the integration so that they can subscribe.  

The admin permission gives a user or group.  

When adding a permission, you must specify at least one permission to add.

Giving a user or group admin permissions automatically also gives that user or group read permissions.

Group IDs

Group IDs are the unique numeric identifier for the group you want to add permissions to.  Group IDs can represent a group of users or a single user.  

The Group ID for a single user is not the same as the user's user ID

You can determine the Group ID for a user via the groups endpoint.

If you want to provide all users access to an integration you can leverage the "All Polarity Users" group which always has a group id of 1.

CURL

curl -v -X POST \
'https://<polarity.server.url>/api/integrations/<INTEGRATION_ID>/permissions' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
--data-binary @- <<EOF
{
  "data": [
    {
      "type": "permissions",
      "attributes": {
        "permissions": [
          "read"
        ]
      },
      "relationships": {
        "group": {
          "data": {
            "type": "groups",
            "id": "<GROUP_ID>"
          }
        },
        "integration": {
          "data": {
            "type": "integrations",
            "id": "<INTEGRATION_ID>"
          }
        }
      }
    }
  ]
}
EOF

Python

import requests
import json

def add_read_permission(token, host, integration_id, group_id):
    url = f'{host}/api/integrations/{integration_id}/permissions'

    payload = json.dumps({
      "data": [
        {
          "type": "permissions",
          "attributes": {
            "permissions": [
              "read"
            ]
          },
          "relationships": {
            "group": {
              "data": {
                "type": "groups",
                "id": group_id
              }
            },
            "integration": {
              "data": {
                "type": "integrations",
                "id": integration_id
              }
            }
          }
        }
      ]
    })
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

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

    return response.json()
    
update_result = add_read_permission(token, HOST, 'virustotal_3_7_4_node_18_63e5110da4_1697729362', 1)  

Updating Permissions

When updating permissions, for example, changing read, admin permissions to just read you use the same endpoint as when adding permissions.

For example, if a user already has admin and read permissions to an integration you can remove admin permission by using the same POST endpoint but only specifying the read permission.  This will remove the admin permission.  

Similarly, if you want to add admin permission to a user that already has read permission, use the same endpoint but specify admin as the provided permission.

Removing All Permissions

You can remove all permissions for a user or group from an integration by sending an HTTP DELETE request to the integration's permission relationship endpoint.  Removing all permissions removes access for the user or group from the user (i.e., the user or group will no longer be able to view or subscribe to the integration).

DELETE https://<polarity.server.url>/api/integrations/<INTEGRATION_ID>/relationships/permissions
{
  "data": [
    {
      "type": "permissions",
      "id": "integration:<INTEGRATION_ID>:<GROUP_ID>"
    }
  ]
}

The permission ID is constructed by knowing the id of the integration you are removing permissions from and the group_id.