Role
Entity - Role Based Access Control - Interrogates the Roles table in the database
Verb | Request | Notes | Permissions required |
|---|---|---|---|
GET - all | /Consumer/Roles | Gets list of all Roles |
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"
} |
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. |
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"
} |
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"
} |
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". |
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.
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 Expand source {
"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 Expand source {
"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.
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 Expand source {
"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 Expand source {
"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 Expand source {
"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 Expand source {
"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 |