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}

Create a role¶

POST /roles

Request:

Name	Position	Type	Required
request	body	RoleCreateRequest	required

Response: RoleResponse

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

Response: RolesResponse

RolesResponse¶

required
roles [RoleResponse]

Add and remove assigned roles for a user¶

PATCH /account/{userLocator}/roles

Request:

Name	Position	Type	Required
request	body	AccountRoleUpdateRequest	required
userLocator	path	string	required

Response: RolesResponse

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}

Request:

Name	Position	Type	Required
request	body	RoleUpdateRequest	required
roleName	path	string	required

Response: RoleResponse

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:

Name	Position	Type	Required
roleName	path	string	required

Response: void