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 HID Authentication Service is 10.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. For details of the version updates, see SCIM API Revision History.

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
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.

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