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

Page version: 20, 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

Obsolete as of API version 8.0 . Retained for backwards compatibility. Will work as suggested /PrincipalRoleManagementGroup equivalent.

  • 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/SearchWithCounts

Minimum API version 8.0

Works in the same way as /Consumer/Roles/Search discussed above, but the returned results include additional fields that indicate the usage count for each returned role. The counts provide the number of Instruction Sets assigned to the role as well as the number of Securable Types on which the Role has one or more permissions, differentiating between local and global securable types.

Sample output
{
    "TotalCount": 37,
    "Items": [
        {
            "InstructionSets": 0,
            "LocalizedOperations": 0,
            "GlobalPermissions": 1,
            "Id": 11,
            "Name": "1E Client Deployment Administrators",
            "Description": "Create, view and cancel 1E Client deployment jobs",
            "CreatedTimestampUtc": "2020-02-21T09:23:34.047Z",
            "ModifiedTimestampUtc": "2020-04-14T15:30:02.953Z",
            "SystemRole": true,
            "CanBeDelegated": false,
            "NumberOfAssignments": 0
        },
      ...
        {
            "InstructionSets": 0,
            "LocalizedOperations": 2,
            "GlobalPermissions": 0,
            "Id": 33,
            "Name": "Survey Viewers",
            "Description": "View surveys",
            "CreatedTimestampUtc": "2020-05-11T09:53:24.4Z",
            "ModifiedTimestampUtc": "2020-05-11T09:53:24.4Z",
            "SystemRole": false,
            "CanBeDelegated": false,
            "NumberOfAssignments": 0
        }
    ]
}

Note that in version 8.0, the "Global Adminstrators" role has become a pseudo-role that automatically receives all possible permissions. The API as discussed above only returns the count of permissions that are explicitly assigned in the database, so it will not count the implicit permissions that are internally granted to the pseudo-role.

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

Removed as of API version 8.0 . Will return 405 if called. It cannot work anymore or be made backwards compatible in a sensible way because Management Groups are no longer linked to Roles through Permissions.

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"
	    }
	]
 
}

Removed as of API version 8.0 . Will return 405 if called. It cannot work anymore or be made backwards compatible in a sensible way because Management Groups are no longer linked to Roles through Permissions.

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"
	    }
	]
 
}

Removed as of API version 8.0 . Will return 405 if called. It cannot work anymore or be made backwards compatible in a sensible way because Management Groups are no longer linked to Roles through Permissions.

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.

Removed as of API version 8.0 . Will return 405 if called. It cannot work anymore or be made backwards compatible in a sensible way because Management Groups are no longer linked to Roles through Permissions.

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.

Removed as of API version 8.0 . Will return 405 if called. It cannot work anymore or be made backwards compatible in a sensible way because Management Groups are no longer linked to Roles through Permissions.

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"
    }]
}

Behaviour changed as of API version 8.0 . The payload sent to the endpoint and returned from it will no longer have Management Group related information because Management Groups are not linked directly to Roles but require a Principal as well. From v8.0 this endpoint can still be used to create a Role with assigned Permissions, but it cannot be used to also link a Management Group to that role, because that type of link no longer exists.

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"
    }]
}

Behaviour changed as of API version 8.0 . The payload sent to the endpoint and returned from it will no longer have Management Group related information because Management Groups are not linked directly to Roles but require a Principal as well. From v8.0 this endpoint can still be used to update a Role with assigned Permissions, but it cannot be used to also link a Management Group to that role, because that type of link no longer exists.

Requires 'Write' on Security