Roles API

Endpoint Index

ActionEndpoint
Create a rolePOST /roles
Get rolesGET /roles
Add and remove assigned roles for a userPATCH /account/{userLocator}/roles
Update a rolePATCH /roles/{roleName}
Delete a roleDELETE /roles/{roleName}

Details

Create a role
POST /roles
  • Role name can 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 displayName can 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 " "

RoleCreateRequest
required
name string
displayName string
permissions [string]
  • The role name and displayName cannot be changed after creating the role.

  • To create a role with no assigned permissions, provide an empty string for the permissions parameter.

RoleResponse
required
name string
displayName string
permissions [string]
Get roles
GET /roles
RolesResponse
required
roles [RoleResponse]
Add and remove assigned roles for a user
PATCH /account/{userLocator}/roles
  • A 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 replaceAll is true, in which case the unassignRoles parameter is ignored.

AccountRoleUpdateRequest
optional
assignRoles [string]
replaceAll boolean
unassignRoles [string]
Update a role
PATCH /roles/{roleName}
RoleUpdateRequest
optional
assignPermissions [string]
replaceAll boolean
unassignPermissions [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 replaceAll is true, in which case the unassignPermissions parameter is ignored.

Delete a role
DELETE /roles/{roleName}
    Request:
    NamePositionTypeRequired
    roleNamepathstringrequired
    Response: void
  • The request will fail if the role is assigned to any user.