Manage custom roles

Custom roles and the User Default role allow you to create and assign specific scopes to users or groups, providing more granular control than the built in roles alone.

In this topic, you will create a new custom role, assign scopes to it, assign the role to a user, update assigned scopes, then delete the role to demonstrate a full lifecycle for a custom role.

Prerequisites

• You have an API key of a user assigned the TenantAdmin role, for use as the <ACCESS_TOKEN> in the examples below.
• cURL for running the inline examples.

1: Create a custom role

When creating a new custom role, it is possible to assign scopes at the point of creation. In this example, you will assign just two scopes from the scopes which support custom roles, which means the role will provide assigned users or groups with image and PDF export from Qlik Sense, and AutoML model approval.

curl --location "https://tenant.region.qlikcloud.com/api/v1/roles" ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json" ^
--header "Accept: application/json" ^
--data "{
    \"name\": \"My first custom role\",
    \"description\": \"This is the first custom role created via API\",
    \"assignedScopes\": [
        \"automl-models:approve\",
        \"apps.image:export\"
    ]
}"

If successful, you’ll be returned a http 201 response with the following body:

{
    "id": "6724d8f5a4acfa155351afa7",
    "tenantId": "BL4tTJ4S7xrHTcq0zQxQrJ5qB1_Q6cSo",
    "name": "My first custom role",
    "description": "This is the first custom role created via API",
    "type": "custom",
    "canEdit": true,
    "canDelete": true,
    "fullUser": false,
    "userEntitlementType": "",
    "level": "user",
    "assignedScopes": [
        "automl-models:approve",
        "apps.image:export"
    ],
    "permissions": [],
    "createdAt": "2024-11-01T13:34:45.511Z",
    "lastUpdatedAt": "2024-11-01T13:34:45.511Z",
    "createdBy": "637390ec6541614d3a88d6c1",
    "updatedBy": "637390ec6541614d3a88d6c1",
    "links": {
        "self": {
            "href": "https://tenant.region.qlikcloud.com/api/v1/roles/6724d87be21e7c1194a9e1a7"
        }
    }
}

Note the id value in the response, as this will be needed for the update and delete steps later on as <ROLE_ID>.

2: Assign the custom role to a user

Assigning a role to a user or a group follows the same process, but using different endpoints. Review the tutorial on assigning roles to learn how to assign roles.

3: Update the custom role’s assigned scopes

If you need to amend the scopes assigned to a custom role, you can do so sending a PATCH request to the update role endpoint.

The role you created earlier has the following definition:

"assignedScopes": [
    "automl-models:approve",
    "apps.image:export"
]

To update the assigned scopes to remove autoML approval permissions, send:

curl --location --request PATCH "https://tenant.region.qlikcloud.com/api/v1/roles/<ROLE_ID>" ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json" ^
--header "Accept: application/json" ^
--data "[
    {
        \"op\": \"replace\",
        \"path\": \"/assignedScopes\",
        \"value\": [
            \"apps.image:export\"
        ]
    }
]"

If successful, you’ll receive an HTTP 204 response with no content.

4: Delete the custom role

Before deleting a custom role, you must ensure that no users or groups are assigned it. Attempting to delete an assigned role will result in an HTTP 403 response. Review the tutorial on assigning roles to learn how to unassign roles.

Once no users or groups are assigned the role, you can delete it using a DELETE call:

curl --location --request PATCH "https://tenant.region.qlikcloud.com/api/v1/roles/<ROLE_ID>" ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json" ^
--header "Accept: application/json"

If successful, you’ll receive an HTTP 204 response with no content. The role is now deleted.