Updating Integration Permissions

Adding Permissions

Integration permissions can be updated via a POSTrequest to the integration's permissions endpoint. The endpoint will return a 204 HTTP status code with no content on success.

Request Path

POST https://<POLARITY_SERVER>/api/integrations/<INTEGRATION_ID>/permissions

Request Body

{
  "data": [
    {
      "type": "permissions",
      "attributes": {
        "permissions": [
          "read",
          "admin"
        ]
      },
      "relationships": {
        "group": {
          "data": {
            "type": "groups",
            "id": "<GROUP_ID>"
          }
        },
        "integration": {
          "data": {
            "type": "integrations",
            "id": "<INTEGRATION_ID>"
          }
        }
      }
    }
  ]
}

Be sure to include the Content-Type header with a value of application/vnd.api+json

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.

Note that giving a user or group "admin" permissions automatically also gives the user or group "read" permissions.

Group IDs

Group IDs are the unqiue numberic 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_FQDN>/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

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" permission 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).

Request Path

DELETE https://pp-dev.corp.polarity.io/api/integrations/<INTEGRATION_ID>/relationships/permissions

Request Body

{
  "data": [
    {
      "type": "permissions",
      "id": "integration:<INTEGRATION_ID>:<GROUP_ID>"
    }
  ]
}

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