Manage groups

In this tutorial, you will learn how to create, manage, and delete groups using Qlik Cloud management APIs.

Groups are used for access control and sharing of content in Qlik Cloud. They are most commonly populated from your Identity Provider, either as users log in or via SCIM if you are using a compatible Identity Provider such as Azure AD.

There are three types of groups within Qlik Cloud:

• Identity Provider managed groups: these groups are created by your Identity Provider as users log in or manually via APIs.
• Custom groups: these user-defined groups are created and managed within the Qlik Cloud tenant.
• Qlik system groups: these groups are created and managed by Qlik. For example, the “Everyone” group automatically contains every user in the tenant.

Overview of groups

Groups enable tenant administrators to manage permissions based on group memberships. You can assign security roles and space roles to Identity Provider managed groups and custom groups to control permissions across the tenant.

Identity Provider managed groups

Identity Provider managed groups are synchronized with your Identity Provider. Deleting these groups from a tenant will not prevent them from reappearing. You will need to update your Identity Provider configuration to filter these groups out of user claims before they are sent to Qlik Cloud. For more information on configuring Identity Providers, see Identity providers in Qlik Cloud.

Using Identity Provider managed groups delegates the majority of access control in the platform to your Identity Provider. Any Identity Provider managed group created in your tenant via API relies on relationships passed via the user’s claims from the Identity Provider.

Note: Identity Provider managed groups must be passed in a valid claim from your chosen Identity Provider in order to be associated with a user. You cannot manage the relationship between users and these groups in Qlik Cloud.

Custom groups

Custom groups can be created, updated, and deleted entirely using Qlik APIs. Tenant administrators can create, edit, delete, and manage custom groups. Both Qlik Account users and users provisioned from Identity Providers can be added to custom groups.

Considerations for using custom groups:

• You can create a custom group with the same name as an existing Identity Provider managed group, but not another custom group. You can also create an Identity Provider managed group with the same name as an existing custom group. The differentiator between group types is the prefix (Custom or IDP).
• To avoid confusion, it is recommended to use unique group names. For example, you can prefix custom group names with CG- to distinguish them easily.
• Identity Provider managed groups and custom groups have different icons in the user interface, making it easier to distinguish between them.
• Custom groups support Section Access. For more information, see Managing data security with Section Access.

Qlik system groups

Qlik system groups are created and managed by Qlik. You cannot delete them or update their membership, name, and other properties.

Prerequisites

• You have a basic understanding of Qlik Cloud and its access control rules for creating content and managing spaces.
• cURL for running the inline examples.
• qlik-cli@1.5.0 or greater if running qlik-cli commands.

Note: The cURL examples in this topic show the command syntax for Windows Command Prompt. If you are using another command line interface, different syntax may be required for line continuation. You may also need to adjust the number and type of quotes surrounding the parameters and their values.

Variable substitution

Throughout this tutorial, variables are used as placeholder values. The variable substitution format is <VARIABLE_NAME>. The following table lists the variables referenced in this tutorial.

Create a custom group and assign a role to it

Creating groups on the tenant facilitates the setup of spaces and security before users first log in. By assigning roles, space access, or section access to groups, you remove the need to assign these to each user. This also means that the user has immediate access to the required content as soon as they log in, without waiting for someone to add them to a resource.

For a description of the various security roles that can be applied to groups, see Assigning security roles and custom roles.

Note:

• Roles are case sensitive.
• For a full list of tenant roles, refer to the List Roles endpoint.
• For a full list of space roles, retrieve the space using the List Spaces endpoint.

The following cURL example shows you how to create a custom group and assign the Developer role to it:

curl -L "https://<TENANT>/api/v1/groups" ^
-X POST ^
-H "Content-Type: application/json" ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-d "{\"name\": \"<GROUP_NAME>\", \"status\": \"active\", \"providerType\": \"custom\", \"assignedRoles\": [{\"name\": \"Developer\"}]}"

The API returns a JSON object containing the details of the created group. The id field corresponds to the <GROUP_ID>. You will need this <GROUP_ID> to update group roles in the next section of this tutorial.

{
    "id": "649c6d64cf28896726e572ae",
    "tenantId": "BL4tTJ4S7xrHTcq0zQxQrJ5qB1_Q6cSo",
    "createdAt": "2025-01-24T17:34:46.210Z",
    "lastUpdatedAt": "2025-01-24T17:34:46.210Z",
    "name": "<GROUP_NAME>",
    "status": "active",
    "providerType": "custom",
    "createdBy": "67890d4f54978fef2caa2df5",
    "updatedBy": "67890d4f54978fef2caa2df5",
    "assignedRoles": [
        {
            "id": "608050f7634644db3678b1a2",
            "name": "Developer",
            "type": "default",
            "level": "user"
        }
    ],
    ...
}

List groups

Once you have the ID of a group, you can update its roles, assign it to spaces, or use it with section access.

Note: The List Groups endpoint does not return Identity Provider managed, custom, and Qlik system groups in the same response. To retrieve all groups in the tenant, you will need to make two separate API calls.

List Identity Provider managed and custom groups

To retrieve groups that have been created via API calls or your Identity Provider, you can leverage all available filters on the List Groups endpoint, with systemGroups left blank or set to false.

curl -L "https://<TENANT>/api/v1/groups" ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-H "Content-Type: application/json"

This will return only the Identity Provider managed and custom groups in the tenant.

List Qlik system groups

To retrieve system groups, use the same List Groups endpoint but set systemGroups to true. No other filters can be applied when using this parameter.

curl -L "https://<TENANT>/api/v1/groups?systemGroups=true" ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-H "Content-Type: application/json"

This will return the system groups, which have present names and IDs that are the same across all tenants. For example, the Everyone group manifests as:

{
    "data": [
        {
            "id": "000000000000000000000001",
            "tenantId": "BL4tTJ4S7xrHTcq0zQxQrJ5qB1_Q6cSo",
            "createdAt": "2023-05-25T07:52:58.816Z",
            "lastUpdatedAt": "2023-05-25T07:52:58.816Z",
            "name": "com.qlik.Everyone",
            "status": "active",
            "assignedRoles": [],
            ...
        }
    ],
    ...
}

Assigning a role to the Everyone group will provide that capability to all users in the tenant.

Update roles assigned to a group

This step shows you how to replace any existing group assignments with two new assignments for TenantAdmin and Developer. It is not possible to add or remove individual roles from a group.

curl -L "https://<TENANT>/api/v1/groups/<GROUP_ID>" ^
-X PATCH ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-H "Content-Type: application/json" ^
-d "[{\"op\": \"replace\", \"path\": \"/assignedRoles\", \"value\": [ {\"name\": \"TenantAdmin\"}, {\"name\": \"Developer\" }]}]"

The response from this request is an HTTP 204 status code, indicating that the update was successful. There are no additional details provided in the response.

Delete a group

You can delete Identity Provider managed groups in your tenant. If you have enabled Automatic group creation on login, these groups will be recreated the next time a user with that group in their claims logs in.

You can also delete custom groups in your tenant, but only if no users are assigned to the group.

To delete a group, first retrieve the group ID using the List Groups endpoint. Then, use the following API call:

curl -L "https://<TENANT>/api/v1/groups/<GROUP_ID>" ^
-X DELETE ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-H "Content-Type: application/json"

The response from this request is an HTTP 204 status code, indicating that the deletion was successful. There are no additional details provided in the response.

Delete all groups

You may also need to remove all groups in a tenant to support scenarios such as when your Identity Provider has sent:

• GUIDs rather than friendly group names
• All groups, rather than groups related to Qlik Cloud
• Groups that you need to remove prior to configuring a different Identity Provider

You are going to learn how to use qlik-cli in PowerShell and Application Automation to delete one or more unwanted groups.

# Retrieve the list of groups
$groups=$(qlik group ls --limit 1000) | ConvertFrom-Json

# Write out count of groups returned
Write-Host $groups.count "groups returned."

# Loop over each group if you have more than 0
if ($groups.count -ne 0) {

    $groups | ForEach {

        $group = $_.id
        Write-Host "Deleting group" $_.name
        $deleteResponse=$(qlik group rm $_.id)
    }
} else {
    Write-Host "No groups found."
}

# Retrieve the list of groups
$groups=$(qlik group filter --filter 'name eq ""DeleteMeGroup""' --limit 1000) | ConvertFrom-Json

# Write out count of groups returned
Write-Host $groups.count "groups returned."

# Loop over each group if you have more than 0
if ($groups.count -ne 0) {

    $groups | ForEach {

        $group = $_.id
        Write-Host "Deleting group" $_.name
        $deleteResponse=$(qlik group rm $_.id)
    }
} else {
    Write-Host "No groups found."
}

Delete all groups (no-code)

If you prefer no-code methods, consider leveraging no-code tools such as the Qlik Cloud or Platform Operations connectors in Application Automation.

This example will loop over every group in the tenant running the automation and delete each group as it goes.

To recreate this automation, copy the snippet below and paste it into an automation workspace in edit mode.

{"blocks":[{"id":"890DEEAB-7B43-4A03-BCA0-D5391B8F0CDF","type":"StartBlock","disabled":false,"name":"Start","displayName":"Start","comment":"","childId":"12D0C652-2AE2-4D9B-A5FD-692FFFB0CEBF","inputs":[{"id":"run_mode","value":"manual","type":"select","structure":{}}],"settings":[],"collapsed":[{"name":"loop","isCollapsed":false}],"x":0,"y":0},{"id":"416F1CEE-6226-42ED-9081-4639A939DE94","type":"EndpointBlock","disabled":false,"name":"rawAPIRequest2","displayName":"Qlik Cloud Services - Raw API Request 2","comment":"Call DELETE /api/v1/groups/group-id to delete each group","childId":null,"inputs":[{"id":"4add8960-2078-11ec-be2c-7fc55d771fe6","value":"groups/{$.rawAPIListRequest.item.id}","type":"string","structure":[]},{"id":"3b992a40-2072-11ec-9f0e-ed01586a7e1b","value":"3ba2a970-2072-11ec-be02-2dd5c73abb12","type":"select","displayValue":"DELETE","structure":[]},{"id":"3b8b9090-2072-11ec-8c77-5195fbb0ca65","value":null,"type":"object","mode":"keyValue","structure":[]},{"id":"993585d0-2839-11ec-b431-df4deed6c1ae","value":null,"type":"object","mode":"keyValue","structure":[]}],"settings":[{"id":"blendr_on_error","value":"stop","type":"select","structure":[]},{"id":"cache","value":"0","type":"select","structure":[]}],"collapsed":[{"name":"loop","isCollapsed":false}],"x":526,"y":220,"datasourcetype_guid":"61a87510-c7a3-11ea-95da-0fb0c241e75c","endpoint_guid":"3b75dd80-2072-11ec-9043-3b2aff6123af","endpoint_role":"get"},{"id":"12D0C652-2AE2-4D9B-A5FD-692FFFB0CEBF","type":"EndpointBlock","disabled":false,"name":"rawAPIListRequest","displayName":"Qlik Cloud Services - Raw API List Request","comment":"Call /api/v1/groups to get list of groups","childId":null,"inputs":[{"id":"c3a1c780-2076-11ec-98c4-dd329f9ef682","value":"groups","type":"string","structure":[]},{"id":"c6915fb0-2839-11ec-a450-03c7d8aebbe7","value":null,"type":"object","mode":"keyValue","structure":[]}],"settings":[{"id":"maxitemcount","value":"","type":"string","structure":[]},{"id":"blendr_on_error","value":"stop","type":"select","structure":[]},{"id":"cache","value":"0","type":"select","structure":[]}],"collapsed":[{"name":"loop","isCollapsed":false}],"x":-258,"y":149,"loopBlockId":"416F1CEE-6226-42ED-9081-4639A939DE94","datasourcetype_guid":"61a87510-c7a3-11ea-95da-0fb0c241e75c","endpoint_guid":"4b993580-2072-11ec-8f59-e5aaa8656a36","endpoint_role":"list"}],"variables":[]}