Roles

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.

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.

System-generated roles are denoted by "::SYS::" in the ID.

Permissions and other requirements
SubscriptionAdministration
ConfigurationRole-based
User typeBusiness user with admin privileges
PermissionsList, View Users
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": null,
    • "previous": null
    }
}

Create a role

post/objects/company-config/role

Creates a new role.

Permissions and other requirements
SubscriptionAdministration
ConfigurationRole-based
User typeBusiness user with admin privileges
PermissionsAdd Users
SecurityOAuth2
Request
Request Body schema: application/json
required
id
required
string

Unique ID for the role. Cannot be changed after the role is created.

Note that the id values for system-generated roles begin with ::SYS::.

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.

  • enterprise: A single entity company with unique chart of accounts.
  • eConsole: Accountant or Partner console.
  • multiEntityDistributed: Separate companies with different charts of accounts accessed from a Management console.
  • multiEntityShared: Multiple units or locations with the same chart of accounts.
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

Array of permissions and access rights for the role.

Array
object

Permission assigned to the role.

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"]
Array of objects

Array of permissions for custom applications.

Array
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": "Admins",
  • "description": "Administrator role with permissions",
  • "roleType": "enterprise",
  • "applyTo": "loginAndSlideIn",
  • "rolePermissionAssignments": [
    • {
      • "permission": {
        },
      • "accessRights": [
        ]
      },
    • {
      • "permission": {
        },
      • "accessRights": [
        ]
      }
    ],
  • "customRolePermissionAssignments": [
    • {
      • "application": {
        },
      • "accessRights": [
        ]
      }
    ]
}
Response samples
application/json
{
  • "ia::result": {
    • "key": "470",
    • "id": "Admins",
    • "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.

Permissions and other requirements
SubscriptionAdministration
ConfigurationRole-based
User typeBusiness user with admin privileges
PermissionsList, View Users
SecurityOAuth2
Request
path Parameters
key
required
string

System-assigned unique key for the role.

Example: 470
Responses
200

OK

400

Bad Request

Request samples
Response samples
application/json
{
  • "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": [
      • {
        }
      ],
    • "customRolePermissionAssignments": [
      • {
        },
      • {
        }
      ],
    • "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.

Permissions and other requirements
SubscriptionAdministration
ConfigurationRole-based
User typeBusiness user with admin privileges
PermissionsEdit Users
SecurityOAuth2
Request
path Parameters
key
required
string

System-assigned unique key for the role.

Example: 470
Request Body schema: application/json
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.

  • enterprise: A single entity company with unique chart of accounts.
  • eConsole: Accountant or Partner console.
  • multiEntityDistributed: Separate companies with different charts of accounts accessed from a Management console.
  • multiEntityShared: Multiple units or locations with the same chart of accounts.
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

Array of permissions and access rights for the role.

Array
object

Permission assigned to the role.

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"]
Array of objects

Array of permissions for custom applications.

Array
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": [
        ]
      }
    ],
  • "customRolePermissionAssignments": [
    • {
      • "application": {
        },
      • "accessRights": [
        ]
      }
    ]
}
Response samples
application/json
{
  • "ia::result": {
    • "key": "470",
    • "id": "Admins",
    • "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.

Permissions and other requirements
SubscriptionAdministration
ConfigurationRole-based
User typeBusiness user with admin privileges
PermissionsDelete Users
SecurityOAuth2
Request
path Parameters
key
required
string

System-assigned unique key for the role.

Example: 470
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

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