Roles

Roles can be defined for various job functions. Permissions to perform certain tasks can be assigned to specific roles, and roles can then be assigned to users or user groups.

List roles

get/objects/company-config/role

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.

SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples 
Response samples 
application/json
{
  • "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": 101,
    • "previous": null
    }
}
Create a role
post/objects/company-config/role
Creates a new role.


SecurityOAuth2 
Request 
Request Body schema: application/json
Role to create


id
required
string
Role Id


 
 Example:  "Employee"
description
string
Description


 
 Example:  "Full employee permissions including approvals"
roleType
string
 Default:  "enterprise"
Role type


 Enum: "eConsole" "enterprise" "multiEntityDistributed" "multiEntityShared"  
 Example:  "enterprise"
applyTo
string
 Default:  "loginAndSlideIn"
Role is applicable to users with specified access method.


 Enum: "loginAndSlideIn" "loginOnly" "slideInOnly"  
 Example:  "loginAndSlideIn"
Array of objects
List of permission assignments for a specific role


 
 Array 
object
Permission object


 
accessRights
Array of strings
Permission access rights.


Items Enum: "ach" "achSetup" "add" "addExpense" "apiProxy" "approvalLevel1" "approvalLevel2" "approvalLevel3" "approvalLevel4" "approvalLevel5" "approvalLevel6" "authorize" "calendar" "cancel" "clone" "close" "config" "confirm" "delete" "deleteExpense" "edit" "editExpense" "enable" "export" "final" "financial" "group" "ignore" "impersonate" "import" "level1" "level2" "level3" "level4" "level5" "level6" "list" "listExpenses" "manualMatch" "mapAccount" "menu" "modify" "offsetAccount" "open" "overrideException" "permission" "post" "print" "readonly" "readonlyExpense" "receipts" "reclass" "reclassExpense" "reconcile" "refresh" "release" "reopen" "report" "resend" "reversalEdit" "reverse" "reverseExpense" "run" "statutoryReportingPeriod" "submit" "subscribe" "template" "uncancel" "unmask" "upload" "view" "viewAll" "void"  
 Example:  ["list","readonly","add","modify","delete"]
Responses 
201
Created


400
Bad Request


Request samples 
application/json
{
  • "id": "::SYS::Multi Entity Shared-ROLE-FOR - Admin",
  • "description": "Administrator role with permissions",
  • "roleType": "enterprise",
  • "applyTo": "loginAndSlideIn",
  • "rolePermissionAssignments": [
    • {
      • "permission": {
        },
      • "accessRights": [
        ]
      },
    • {
      • "permission": {
        },
      • "accessRights": [
        ]
      }
    ]
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "470",
    • "id": "::SYS::Multi Entity Shared-ROLE-FOR - Admin",
    • "href": "/objects/company-config/role/470"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Get a role
get/objects/company-config/role/{key}
Returns detailed information for a specified role.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned unique key for the role.


 
 Example:  32
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "key": "470",
    • "id": "::SYS::Multi Entity Shared-ROLE-FOR - Admin",
    • "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": [
      • {
        }
      ],
    • "roleUsers": [
      • {
        }
      ],
    • "roleGroups": [
      • {
        }
      ],
    • "href": "/objects/company-config/role/470"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Update a role
patch/objects/company-config/role/{key}
Updates an existing role by setting field values. Any fields not provided remain unchanged.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned unique key for the role.


 
 Example:  32
Request Body schema: application/json
description
string
Description


 
 Example:  "Full employee permissions including approvals"
roleType
string
 Default:  "enterprise"
Role type


 Enum: "eConsole" "enterprise" "multiEntityDistributed" "multiEntityShared"  
 Example:  "enterprise"
applyTo
string
 Default:  "loginAndSlideIn"
Role is applicable to users with specified access method.


 Enum: "loginAndSlideIn" "loginOnly" "slideInOnly"  
 Example:  "loginAndSlideIn"
Array of objects
List of permission assignments for a specific role


 
 Array 
object
Permission object


 
accessRights
Array of strings
Permission access rights.


Items Enum: "ach" "achSetup" "add" "addExpense" "apiProxy" "approvalLevel1" "approvalLevel2" "approvalLevel3" "approvalLevel4" "approvalLevel5" "approvalLevel6" "authorize" "calendar" "cancel" "clone" "close" "config" "confirm" "delete" "deleteExpense" "edit" "editExpense" "enable" "export" "final" "financial" "group" "ignore" "impersonate" "import" "level1" "level2" "level3" "level4" "level5" "level6" "list" "listExpenses" "manualMatch" "mapAccount" "menu" "modify" "offsetAccount" "open" "overrideException" "permission" "post" "print" "readonly" "readonlyExpense" "receipts" "reclass" "reclassExpense" "reconcile" "refresh" "release" "reopen" "report" "resend" "reversalEdit" "reverse" "reverseExpense" "run" "statutoryReportingPeriod" "submit" "subscribe" "template" "uncancel" "unmask" "upload" "view" "viewAll" "void"  
 Example:  ["list","readonly","add","modify","delete"]
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "description": "Administrator role with permissions",
  • "rolePermissionAssignments": [
    • {
      • "key": "30",
      • "accessRights": [
        ]
      },
    • {
      • "permission": {
        },
      • "accessRights": [
        ]
      }
    ]
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "470",
    • "id": "::SYS::Multi Entity Shared-ROLE-FOR - Admin",
    • "href": "/objects/company-config/role/470"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Delete a role
delete/objects/company-config/role/{key}
Deletes a role.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned unique key for the role.


 
 Example:  32
Responses 
204
No Content


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}
Query roles
post/services/core/query
Use the query service to find roles that meet certain criteria and to specify the properties that are returned.


SecurityOAuth2 
Responses 
200
OK


Request samples