Roles API
Endpoint Index
| Action | Endpoint |
|---|---|
| Create a role | POST /roles |
| Get roles | GET /roles |
| Add and remove assigned roles for a user | PATCH /account/{userLocator}/roles |
| Update a role | PATCH /roles/{roleName} |
| Delete a role | DELETE /roles/{roleName} |
Details
POST /roles| Name | Position | Type | Required |
|---|---|---|---|
| request | body | RoleCreateRequest | required |
RoleResponseRole
namecan be up to 256 characters long and can include letters and numbers (a-z,A-Z,0-9) and the following special characters:hyphen
-tilde
~underscore
_
Role
displayNamecan be up to 256 characters long and can include letters and numbers (a-z,A-Z,0-9) and the following special characters:hyphen
-tilde
~underscore
_asterisk
*exclamation point
!parentheses
()period
.space
" "
requiredname stringdisplayName stringpermissions [string]
The role
nameanddisplayNamecannot be changed after creating the role.To create a role with no assigned permissions, provide an empty string for the
permissionsparameter.
requiredname stringdisplayName stringpermissions [string]
GET /rolesRolesResponserequiredroles [RoleResponse]
PATCH /account/{userLocator}/roles| Name | Position | Type | Required |
|---|---|---|---|
| request | body | AccountRoleUpdateRequest | required |
| userLocator | path | string | required |
RolesResponseA request that includes no role assignments for a user is valid – to support both new users or users who have left the organization.
Including the same role as both an added and removed will result in an error unless
replaceAllis true, in which case theunassignRolesparameter is ignored.
optionalassignRoles [string]replaceAll booleanunassignRoles [string]
PATCH /roles/{roleName}| Name | Position | Type | Required |
|---|---|---|---|
| request | body | RoleUpdateRequest | required |
| roleName | path | string | required |
RoleResponseoptionalassignPermissions [string]replaceAll booleanunassignPermissions [string]
A request with no permission assignments for a role is valid to support removing permissions for a group of users.
Including the same permissions as both adding assignment and removing assigned permissions will result in an error unless
replaceAllis true, in which case theunassignPermissionsparameter is ignored.
DELETE /roles/{roleName}| Name | Position | Type | Required |
|---|---|---|---|
| roleName | path | string | required |
voidThe request will fail if the role is assigned to any user.