Account user role assignment
This topic discusses how to work with user roles on an account.
Overview of account user role assignment
In the context of an account, a role (such as Underwriter) can be assigned
to a user and group (such as Alice Applegate from the Los Angeles Branch UW group).
The roles that can be assigned are defined in the UserRoles
typelist.
Some account role assignment occurs automatically. For example, the Creator role is assigned automatically to the user who creates an account. Account user roles can also be assigned manually.
A single user can have multiple roles on an account. However, a single account role cannot be held by more than one user.
In Cloud API, account user roles are managed through a roles
array.
Every member of the array has the following structure:
For example, the following roles
array identifies Alice Applegate
(pc:8) from the Los Angeles Branch UW group (pc:55) as the Creator and Underwriter
for the account.
Retrieving account user roles
Use the following endpoint to retrieve a list of user role assignments for an account:
- GET
/account/v1/accounts/{accountId}/user-roles
Here's an example:
Command
Response
Assigning account user roles
Use the following endpoint to assign an account role to a user on a given account:
- POST
/account/v1/accounts/{accountId}/user-roles/assign
The request body must specify the user, group, and role. Each call consists of one role being assigned to a group and user. If that role was already assigned to another user for the account, it is reassigned to the specified user.
For example, the following assigns the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117) on account pc:9.
Command
Request
Updating account user roles
Use the following endpoint to update the role assignment for an account:
- PATCH
/account/v1/accounts/{accountId}/user-roles
You can use the PATCH endpoint to add or remove multiple role assignments in one call.
PATCHes in Cloud API are destructive, not additive. When you PATCH the
roles
array, the new content replaces the previous content
entirely.
If you want to only add user role assignments to an account, the PATCH must
contain all current members of the roles
array as well as the new
one.
- To add multiple role assignments or reassignments, add multiple new
entries to the
roles
array. - To remove role assignments, omit those entries from the
roles
array. - If there are assignments you do not want to change, you must also
include those assignments in the
roles
array.
For example, suppose account pc:9 has already assigned the roles of Creator and Underwriter to Alice Applegate (pc:8) from the Los Angeles Branch UW group (pc:55) and the role of Customer Rep to Chris Clark (pc:303) from the Los Angeles Branch UW group (pc:55). The following PATCH performs these actions:
- Adds the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117).
- Unassigns the role of Customer Rep. (This is done by omitting it from
the
roles
array.) - Makes no changes to the Creator or Underwriter roles. (They are
included in the
roles
array with their original data.)
Command
Request