Roles are used in companies that have role-based permissions. Companies with user-based permissions do not use roles.
A role is basically a group of permissions. Roles save time and make it easier to assign the same set of permissions to multiple users and to ensure that permissions are consistent across users. Permissions to perform certain tasks are assigned to specific roles, and roles can then be assigned to users or user groups. You use role-permission-assignment objects to assign permissions to roles.
You can define roles for various job functions. For example, you can assign all Accounts Receivable clerks the same role instead of assigning permissions to each of them individually. Or when an employee leaves the company, you can assign their role to their replacement. This ensures that the new employee has the same permissions.
You can assign more than one role to a user. The user will then have all permissions for each role. For example, you assign Role A and Role B to a user. Role A has permissions that Role B does not. The user has all permissions in Role A plus the ones in Role B. A user can be individually assigned roles and also be part of a group that has a role. The user gets the total permissions from all assigned roles.
If a company uses role-based permissions, you must assign each user to a role or to a user group that's assigned to a role. If a user does not have an associated role, they will not be able to access applications and features.
Returns a collection with a key, ID, and link for each role. This operation is mostly for use in testing; use the query service to find roles that meet certain criteria and specify the properties that are returned.
System-generated roles are denoted by "::SYS::" in the ID.
Subscription | Administration |
---|---|
Configuration | Role-based |
User type | Business user with admin privileges |
Permissions | List, View Users |
OK
Bad Request
{- "ia::result": [
- {
- "key": "470",
- "id": "::SYS::Multi Entity Shared-ROLE-FOR - Admin",
- "href": "/objects/company-config/role/470"
}, - {
- "key": "471",
- "id": "::SYS::Multi Entity Shared-ROLE-FOR - BTI",
- "href": "/objects/company-config/role/471"
}
], - "ia::meta": {
- "totalCount": 2,
- "start": 1,
- "pageSize": 100,
- "next": null,
- "previous": null
}
}
Creates a new role.
Subscription | Administration |
---|---|
Configuration | Role-based |
User type | Business user with admin privileges |
Permissions | Add Users |
id required | string Unique ID for the role. Cannot be changed after the role is created. Note that the Example: "Employee" | ||||
description | string Description of the role. Example: "Full employee permissions including approvals" | ||||
roleType | string Default: "enterprise" The type of company in which the role will be used.
Example: "enterprise" | ||||
applyTo | string Default: "loginAndSlideIn" Role is applicable to users with specified access method. Example: "loginAndSlideIn" | ||||
Array of objects Array of permissions and access rights for the role. | |||||
Array
| |||||
Array of objects Array of permissions for custom applications. | |||||
Array
|
Created
Bad Request
{- "id": "Admins",
- "description": "Administrator role with permissions",
- "roleType": "enterprise",
- "applyTo": "loginAndSlideIn",
- "rolePermissionAssignments": [
- {
- "permission": {
- "id": "253"
}, - "accessRights": [
- "list",
- "readonly"
]
}, - {
- "permission": {
- "id": "207"
}, - "accessRights": [
- "list",
- "readonly",
- "add",
- "modify",
- "delete"
]
}
], - "customRolePermissionAssignments": [
- {
- "application": {
- "key": "10004",
- "permission": [
- {
- "name": "Org Department",
- "group": "Objects"
}
]
}, - "accessRights": [
- "list",
- "readonly",
- "modify"
]
}
]
}
{- "ia::result": {
- "key": "470",
- "id": "Admins",
- "href": "/objects/company-config/role/470"
}, - "ia::meta": {
- "totalCount": 1,
- "totalSuccess": 1,
- "totalError": 0
}
}
Returns detailed information for a specified role.
Subscription | Administration |
---|---|
Configuration | Role-based |
User type | Business user with admin privileges |
Permissions | List, View Users |
key required | string System-assigned unique key for the role. Example: 470 |
OK
Bad Request
{- "ia::result": {
- "key": "470",
- "id": "Admins",
- "description": "Administrator role with permissions",
- "roleType": "enterprise",
- "applyTo": "loginAndSlideIn",
- "audit": {
- "createdDateTime": "2020-11-16T14:27:51Z",
- "modifiedDateTime": "2020-11-16T14:28:11Z",
- "createdBy": "1",
- "modifiedBy": "1"
}, - "rolePermissionAssignments": [
- {
- "key": "30",
- "id": "30",
- "role": {
- "key": "470",
- "id": "Admins",
- "href": "/objects/company-config/role/470"
}, - "permission": {
- "key": "253",
- "id": "253",
- "name": "taxScheduleMap",
- "module": "purchasing",
- "href": "/objects/company-config/permission/253"
}, - "accessRights": [
- "list",
- "readonly",
- "add",
- "modify",
- "delete"
]
}
], - "customRolePermissionAssignments": [
- {
- "application": {
- "key": "10004",
- "id": "Custom Application",
- "href": "/objects/platform/custom-application/10004",
- "permission": [
- {
- "name": "Org Department",
- "group": "Objects"
}
]
}, - "accessRights": [
- "list",
- "readonly",
- "modify"
], - "audit": {
- "createdDateTime": "2020-11-16T14:27:51Z",
- "modifiedDateTime": "2020-11-16T14:28:11Z",
- "createdBy": "1",
- "modifiedBy": "1"
}, - "href": "/objects/company-config/role-permission-assignment/30"
}, - {
- "application": {
- "key": "10004",
- "id": "Custom Application",
- "href": "/objects/platform/custom-application/10004",
- "permission": [
- {
- "name": "Org Department",
- "group": "objects"
}
]
}, - "accessRights": [
- "list",
- "readonly",
- "modify"
]
}
], - "roleUsers": [
- {
- "key": "472",
- "id": "472",
- "role": {
- "key": "470",
- "id": "Admins",
- "href": "/objects/company-config/role/470"
}, - "user": {
- "key": "189",
- "id": "Admin",
- "href": "/objects/company-config/user/189"
}, - "audit": {
- "createdDateTime": "2020-11-16T14:27:51Z",
- "modifiedDateTime": "2020-11-16T14:28:11Z",
- "createdBy": "1",
- "modifiedBy": "1"
}, - "href": "/objects/company-config/role-user-map/472"
}
], - "roleGroups": [
- {
- "key": "761",
- "id": "761",
- "role": {
- "key": "470",
- "id": "Admins",
- "href": "/objects/company-config/role/470"
}, - "userGroup": {
- "key": "1",
- "id": "Bypass group",
- "href": "/objects/company-config/user-group/1"
}, - "audit": {
- "createdDateTime": "2020-11-16T14:27:51Z",
- "modifiedDateTime": "2020-11-16T14:28:11Z",
- "createdBy": "1",
- "modifiedBy": "1"
}, - "href": "/objects/company-config/role-user-group-map/761"
}
], - "href": "/objects/company-config/role/470"
}, - "ia::meta": {
- "totalCount": 1,
- "totalSuccess": 1,
- "totalError": 0
}
}
Updates an existing role by setting field values. Any fields not provided remain unchanged.
Subscription | Administration |
---|---|
Configuration | Role-based |
User type | Business user with admin privileges |
Permissions | Edit Users |
key required | string System-assigned unique key for the role. Example: 470 |
description | string Description of the role. Example: "Full employee permissions including approvals" | ||||
roleType | string Default: "enterprise" The type of company in which the role will be used.
Example: "enterprise" | ||||
applyTo | string Default: "loginAndSlideIn" Role is applicable to users with specified access method. Example: "loginAndSlideIn" | ||||
Array of objects Array of permissions and access rights for the role. | |||||
Array
| |||||
Array of objects Array of permissions for custom applications. | |||||
Array
|
OK
Bad Request
{- "description": "Administrator role with permissions",
- "rolePermissionAssignments": [
- {
- "key": "30",
- "accessRights": [
- "list"
]
}, - {
- "permission": {
- "key": "274"
}, - "accessRights": [
- "add"
]
}
], - "customRolePermissionAssignments": [
- {
- "application": {
- "key": "10004",
- "id": "SaaS Subscription Management",
- "permission": [
- {
- "name": "Org Department",
- "group": "Objects"
}
]
}, - "accessRights": [
- "list",
- "readonly",
- "modify"
]
}
]
}
{- "ia::result": {
- "key": "470",
- "id": "Admins",
- "href": "/objects/company-config/role/470"
}, - "ia::meta": {
- "totalCount": 1,
- "totalSuccess": 1,
- "totalError": 0
}
}
Deletes a role.
Subscription | Administration |
---|---|
Configuration | Role-based |
User type | Business user with admin privileges |
Permissions | Delete Users |
key required | string System-assigned unique key for the role. Example: 470 |
No Content
Bad Request
{- "ia::result": {
- "ia::error": {
- "code": "invalidRequest",
- "message": "A POST request requires a payload",
- "errorId": "REST-1028",
- "additionalInfo": {
- "messageId": "IA.REQUEST_REQUIRES_A_PAYLOAD",
- "placeholders": {
- "OPERATION": "POST"
}, - "propertySet": { }
}, - "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
}
}, - "ia::meta": {
- "totalCount": 1,
- "totalSuccess": 0,
- "totalError": 1
}
}
Use the query service to find roles that meet certain criteria and to specify the properties that are returned.
OK
Bad Request
{- "ia::result": {
- "ia::error": {
- "code": "invalidRequest",
- "message": "A POST request requires a payload",
- "errorId": "REST-1028",
- "additionalInfo": {
- "messageId": "IA.REQUEST_REQUIRES_A_PAYLOAD",
- "placeholders": {
- "OPERATION": "POST"
}, - "propertySet": { }
}, - "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
}
}, - "ia::meta": {
- "totalCount": 1,
- "totalSuccess": 0,
- "totalError": 1
}
}