Roles REST API

The Roles endpoint allows creating and managing roles that can be mapped to a permission set.

Note: The API version supported by ActivID AS 8.5 is 3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality.

Method Details

HTTPS Method Entity Action Request URI Description

GET

Read

/scim/{tenant}/v2/Roles

Get the list of all roles

GET

Read

/scim/{tenant}/v2/Roles/{uid}

Get a role

POST

Create

/scim/{tenant}/v2/Roles

Create a role

DELETE

Delete

/scim/{tenant}/v2/Roles/{uid}

Delete a role

Required Permissions

Function Required Permissions

GET

  • Read role

GET ALL

  • Read reference data

CREATE

  • Create role

  • Modify user roles

DELETE

  • Delete role

Get a List of Roles

[GET] /Roles

This endpoint will return all existing roles within the tenant.

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Roles/RL_AUDITV
Copy

Sample Response

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 13,
    "resources": [
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:Role"],
            "id": "RL_AUDITV",
            "meta": {
                "resourceType": "Role",
                "location": "https://[base-server-url]/scim/tenant/v2/Policy/Roles/RL_AUDITV",
                "version": "1"
            },
            "name": "Audit Viewer"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:Role"],
            "id": "RL_CFGMGR",
            "meta": {
                "resourceType": "Role",
                "location": "https://[base-server-url]/scim/tenant/v2/Policy/Roles/RL_CFGMGR",
                "version": "1"
            },
            "name": "Configuration Manager"
        },
    <--truncated output-->
}

Create a Role

[POST] /Roles

Accept: application/scim+json

The updatePermissionSet parameter can be used to define if you want to automatically add the new role to a configured permission set.

By default, this parameter is set to true and will only apply if you have configured a permission set to be updated.

To configure the permission set, edit the ActivID AS activid.properties file in the <ACTIVID_HOME>/ActivID_AS/applications/resources/common/ directory and add the following property and code for the required permission set:

ASSIGN_CUSTOM_ROLES_PERMISSION_SET=<Permission Set Code>

Then restart the ActivID AS applications.

You can test the permission set update using [GET] /PermissionSets (see Get a Permission Set).

Note:

  • The configured permission set must have the Modify User Roles (M_U_ROLES) permission enabled.

  • When a role is deleted, it will also be removed from the permission set.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Roles
Copy

Sample Request

{
    "id": "NEWROLE",
    "name": "New Role",
    "description": "my new role"
    "updatePermissionSet": true
}
Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Role"],
    "id": "NEWROLE",
    "meta": {
        "resourceType": "Role",
        "location": "https://[base-server-url]/scim/tenant/v2/Roles/NEWROLE",
        "version": "1"
    },
    "name": "New Role",
    "description": "my new role",
    "updatePermissionSet": true
}

Get a Role

[GET] /Roles/{uid}

Where {uid} is the Role Code.

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Roles/RL_CONFIG
Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Role"],
    "id": "RL_CONFIG",
    "meta": {
        "resourceType": "Role",
        "location": "https://[base-server-url]/scim/tenant/v2/Roles/RL_CONFIG",
        "version": "1"
    },
    "name": "Configuration",
    "description": "Allows configuring User Repositories, OOB Delivery Gateways, Channels, and Authorization Profiles."
}

Delete a Role

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content