Entity - Role Based Access Control - Interrogates the Roles table in the database

Page version: 19, last updated:



VerbRequestNotesPermissions required
GET - all/Consumer/RolesGets list of all Roles
  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET - single/Consumer/Roles/{roleId}

Gets details for the specified Role ID.

Example Response
{
  "Id": 1,
  "Name": "Administrators",
  "Description": "This role has permissions to everything",
  "CreatedTimestampUtc": "2015-09-15T09:45:58.73",
  "ModifiedTimestampUtc": "2015-09-15T09:45:58.73"
} 
  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET - for a principal/Consumer/Roles/Principal/{principalId}Gets all roles for a specific principal
  • Read

Returns Unauthorized (401) if user does not have the required permissions.

POST/Consumer/Roles/Search

Minimum API version 4.0

This endpoint allows searching for roles based on criteria along with sorting and pagination.

Example request
{  
   "filter":{
     "Attribute":"Name",
     "Operator":"LIKE",
     "Value":"%Administrator%"
   },
   "start":10,
   "pageSize":100,
   "sort":[
       {
            "Column":"SystemRole",
            "Direction":"DESC"
       }
    ]
}
Requires 'Read' on 'Security'
POST/Consumer/Roles

Creates a Role record.

Example Request
{
  "Name": "Administrators",
  "Description": "This role has permissions to everything" 
} 
  • Write

Returns Unauthorized (401) if user does not have the required permissions.

PUT/Consumer/Roles

Modifies an existing Role.

Example Request
{
  "Id": 1,
  "Name": "Administrators",
  "Description": "This role has permissions to everything"  
} 
  • Write

Returns Unauthorized (401) if user does not have the required permissions.

DELETE/Consumer/Roles/{roleId}  

Deletes the specified Role if it exists, otherwise "ExceptionMessage": "Role record with Id={roleId} was not found".

  • Delete

Returns Unauthorized (401) if user does not have the required permissions.

DELETE/Consumer/Roles

Minimum API version 4.0

Deletes multiple roles.

System roles cannot be deleted.

Body or the request should contain an array of Role Ids.

Requires 'Delete' on Security
GET/Consumer/Roles/{id}/ManagementGroups

Minimum API version 3.3

Returns all Management Groups given role has permissions to access

Requires 'Read' on Security
POST/Consumer/Roles/{roleId}/ManagementGroups/{managementGroupId}

Minimum API version 3.3

Adds permission to use given Management Group to given Role.

  • roleId - Id of the Role to which the permission should be granted.
  • managementGroupId - Id of the Management Group to which the permission in granted.

Return payload will contain the Role in question and all Management Groups that Role has permissions on, not only the ones that have been added.

Sample Response payload
{
	"Role": {
		"Id": 1,
		"Name": "Administrators",
		"Description": "This role has permissions to everything",
		"CreatedTimestampUtc": "2015-09-15T09:45:58.73",
		"ModifiedTimestampUtc": "2015-09-15T09:45:58.73"
	},
	"ManagementGroups": [
    	{
	        "Id": "1",
	        "Name": "Management Group A",
	        "Description": "",
	        "Expression": "",
	        "Count": "12",
	        "UsableId": "0E9514B6-FD77-4077-9B54-A2AAA0C1953C",
	        "HashOfMembers": "5c9f347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5b754"
	    },{
	        "Id": "2",
	        "Name": "Management Group B",
	        "Description": "",
	        "Expression": "",
	        "Count": "7",
	        "UsableId": "AD9514B6-FD77-4077-9B54-A2AAA0C1953C",
	        "HashOfMembers": "ddff347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5bbcc"
	    }
	]
 
}


Requires 'Write' on Security
POST/Consumer/Roles/ManagementGroups

Minimum API version 3.3

Adds permission to use specified Management Groups to given Role.

Sample Request payload
{
	"RoleId": 1,
	"ManagementGroupIds": [1,2,3]
}

Return payload will contain the Role in question and all Management Groups that Role has permissions on, not only the ones that have been added.

Sample Response payload
{
	"Role": {
		"Id": 1,
		"Name": "Administrators",
		"Description": "This role has permissions to everything",
		"CreatedTimestampUtc": "2015-09-15T09:45:58.73",
		"ModifiedTimestampUtc": "2015-09-15T09:45:58.73"
	},
	"ManagementGroups": [
    	{
	        "Id": "1",
	        "Name": "Management Group A",
	        "Description": "",
	        "Expression": "",
	        "Count": "12",
	        "UsableId": "0E9514B6-FD77-4077-9B54-A2AAA0C1953C",
	        "HashOfMembers": "5c9f347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5b754"
	    },{
	        "Id": "2",
	        "Name": "Management Group B",
	        "Description": "",
	        "Expression": "",
	        "Count": "7",
	        "UsableId": "AD9514B6-FD77-4077-9B54-A2AAA0C1953C",
	        "HashOfMembers": "ddff347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5bbcc"
	    }
	]
 
}
Requires 'Write' on Security
DELETE/Consumer/Roles/{roleId}/ManagementGroups/{managementGroupId}

Minimum API version 3.3

Removes permission to use given Management Group to given Role.

  • roleId - Id of the Role from which the permission should be removed.
  • managementGroupId - Id of the Management Group to which the permission in removed.

Return payload is empty.

Requires 'Write' on Security
DELETE/Consumer/Roles/ManagementGroups

Minimum API version 3.3

Removes the permission to use specified Management Groups form given Role.

Sample Request payload
{
	"RoleId": 1,
	"ManagementGroupIds": [1,2,3]
}

Return payload is empty.

Requires 'Write' on Security
POST/Consumer/Roles/Complete

Creates a new role and assigns given permissions and management groups to it

Sample request
{
    "Name": "Complete Role 1",
    "Description": "This is a test role",
    "Permissions": [{
        "SecurableId": 2,
        "SecurableTypeId": 1,
        "Allowed": true,
        "Operations": [{
            "OperationId": 2
        },
        {
            "OperationId": 4
        },
        {
            "OperationId": 3
        },
        {
            "OperationId": 1
        }]
    },
    {
        "SecurableId": 1,
        "SecurableTypeId": 1,
        "Allowed": true,
        "Operations": [{
            "OperationId": 1
        },
        {
            "OperationId": 4
        }]
    }],
    "ManagementGroupIds": [10,11,12]
}
Sample response
{
    "Role": {
        "Id": 1018,
        "Name": "Complete Role 1",
        "Description": "This is a test role",
        "CreatedTimestampUtc": "2018-07-25T07:24:50.0139416Z",
        "ModifiedTimestampUtc": "2018-07-25T07:24:50.0139416Z",
        "SystemRole": false
    },
    "Permissions": [{
        "SecurableId": 1,
        "SecurableName": null,
        "SecurableTypeId": 1,
        "SecurableTypeName": "InstructionSet",
        "RoleId": 1018,
        "RoleName": "Complete Role 1",
        "Allowed": true,
        "Operations": [{
            "PermissionId": 1074,
            "OperationId": 1,
            "OperationName": "Viewer",
            "CreatedTimestampUtc": "2018-07-25T07:24:50.057Z",
            "ModifiedTimestampUtc": "2018-07-25T07:24:50.057Z"
        },
        {
            "PermissionId": 1075,
            "OperationId": 4,
            "OperationName": "Approver",
            "CreatedTimestampUtc": "2018-07-25T07:24:50.057Z",
            "ModifiedTimestampUtc": "2018-07-25T07:24:50.057Z"
        }]
    },
    {
        "SecurableId": 2,
        "SecurableName": null,
        "SecurableTypeId": 1,
        "SecurableTypeName": "InstructionSet",
        "RoleId": 1018,
        "RoleName": "Complete Role 1",
        "Allowed": true,
        "Operations": [{
            "PermissionId": 1070,
            "OperationId": 2,
            "OperationName": "Actioner",
            "CreatedTimestampUtc": "2018-07-25T07:24:50.057Z",
            "ModifiedTimestampUtc": "2018-07-25T07:24:50.057Z"
        },
        {
            "PermissionId": 1071,
            "OperationId": 4,
            "OperationName": "Approver",
            "CreatedTimestampUtc": "2018-07-25T07:24:50.057Z",
            "ModifiedTimestampUtc": "2018-07-25T07:24:50.057Z"
        },
        {
            "PermissionId": 1072,
            "OperationId": 3,
            "OperationName": "Questioner",
            "CreatedTimestampUtc": "2018-07-25T07:24:50.057Z",
            "ModifiedTimestampUtc": "2018-07-25T07:24:50.057Z"
        },
        {
            "PermissionId": 1073,
            "OperationId": 1,
            "OperationName": "Viewer",
            "CreatedTimestampUtc": "2018-07-25T07:24:50.057Z",
            "ModifiedTimestampUtc": "2018-07-25T07:24:50.057Z"
        }]
    }],
    "ManagementGroups": [{
        "Id": 10,
        "Name": "Management group number 9",
        "Description": "This is the description for Management group number 9",
        "Expression": "ADSiteName==Site9",
        "Type": 2,
        "Count": 0,
        "UsableId": "Id-9",
        "HashOfMembers": "29B9C10CF281F598621A069E8B660AE0D518822C870F94CA4D28FBA7F04EC944"
    },
    {
        "Id": 11,
        "Name": "Management group number 10",
        "Description": "This is the description for Management group number 10",
        "Expression": "ADSiteName==Site10",
        "Type": 2,
        "Count": 0,
        "UsableId": "Id-10",
        "HashOfMembers": "803B7F61B5FFD589FA88DD89527A0EA6C32BD1C18C8B3796B26D110AECF6AC12"
    },
    {
        "Id": 12,
        "Name": "Management group number 11",
        "Description": "This is the description for Management group number 11",
        "Expression": "ADSiteName==Site11",
        "Type": 2,
        "Count": 0,
        "UsableId": "Id-11",
        "HashOfMembers": "BA40925847BA8F51113AE9ADE3267F4EF9696BB799B6EBA41FB3376993664DAE"
    }]
}
Requires 'Write' on Security
PUT/Consumer/Roles/Complete

Updates a role and assigns given permissions and management groups.

Any previous permissions are removed.

Any previously linked management groups are unlinked.

Group after update will only have permissions and management groups specified in the request.

Sample request
{
    "Id": 1018,
    "Name": "Complete Role 1",
    "Description": "Updated",
    "Permissions": [{
        "SecurableId": 2,
        "SecurableTypeId": 1,
        "Allowed": true,
        "Operations": [{
            "OperationId": 1
        }]
    },
    {
        "SecurableId": 1,
        "SecurableTypeId": 1,
        "Allowed": true,
        "Operations": [{
            "OperationId": 1
        },
        {
            "OperationId": 2
        },
        {
            "OperationId": 3
        },
        {
            "OperationId": 4
        }]
    }],
    "ManagementGroupIds": [10,20,21]
}
Sample response
{
    "Role": {
        "Id": 1018,
        "Name": "Complete Role 1",
        "Description": "This is a role",
        "CreatedTimestampUtc": "2018-07-25T07:24:50.013Z",
        "ModifiedTimestampUtc": "2018-07-25T13:46:20.8597827Z",
        "SystemRole": false
    },
    "Permissions": [{
        "SecurableId": 1,
        "SecurableName": null,
        "SecurableTypeId": 1,
        "SecurableTypeName": "InstructionSet",
        "RoleId": 1018,
        "RoleName": "Complete Role 1",
        "Allowed": true,
        "Operations": [{
            "PermissionId": 1143,
            "OperationId": 1,
            "OperationName": "Viewer",
            "CreatedTimestampUtc": "2018-07-25T13:46:20.907Z",
            "ModifiedTimestampUtc": "2018-07-25T13:46:20.907Z"
        },
        {
            "PermissionId": 1144,
            "OperationId": 2,
            "OperationName": "Actioner",
            "CreatedTimestampUtc": "2018-07-25T13:46:20.907Z",
            "ModifiedTimestampUtc": "2018-07-25T13:46:20.907Z"
        },
        {
            "PermissionId": 1145,
            "OperationId": 3,
            "OperationName": "Questioner",
            "CreatedTimestampUtc": "2018-07-25T13:46:20.907Z",
            "ModifiedTimestampUtc": "2018-07-25T13:46:20.907Z"
        },
        {
            "PermissionId": 1146,
            "OperationId": 4,
            "OperationName": "Approver",
            "CreatedTimestampUtc": "2018-07-25T13:46:20.907Z",
            "ModifiedTimestampUtc": "2018-07-25T13:46:20.907Z"
        }]
    },
    {
        "SecurableId": 2,
        "SecurableName": null,
        "SecurableTypeId": 1,
        "SecurableTypeName": "InstructionSet",
        "RoleId": 1018,
        "RoleName": "Complete Role 1",
        "Allowed": true,
        "Operations": [{
            "PermissionId": 1142,
            "OperationId": 1,
            "OperationName": "Viewer",
            "CreatedTimestampUtc": "2018-07-25T13:46:20.907Z",
            "ModifiedTimestampUtc": "2018-07-25T13:46:20.907Z"
        }]
    }],
    "ManagementGroups": [{
        "Id": 10,
        "Name": "Management group number 9",
        "Description": "This is the description for Management group number 9",
        "Expression": "ADSiteName==Site9",
        "Type": 2,
        "Count": 0,
        "UsableId": "Id-9",
        "HashOfMembers": "29B9C10CF281F598621A069E8B660AE0D518822C870F94CA4D28FBA7F04EC944"
    },
    {
        "Id": 20,
        "Name": "Management group number 19",
        "Description": "This is the description for Management group number 19",
        "Expression": "ADSiteName==Site19",
        "Type": 2,
        "Count": 0,
        "UsableId": "Id-19",
        "HashOfMembers": "C1F521A70A60FB5BB3EC348D25D8E4B37DB6844428F9A69029D73BE140887C2B"
    },
    {
        "Id": 21,
        "Name": "Management group number 20",
        "Description": "This is the description for Management group number 20",
        "Expression": "ADSiteName==Site20",
        "Type": 2,
        "Count": 0,
        "UsableId": "Id-20",
        "HashOfMembers": "BF92D8BA0315CF4C60FDBF0DACE7C864E5C3062D654A3FB25C434791D380F60C"
    }]
}
Requires 'Write' on Security