A UserRole is a reusable, Organization-scoped permission template. Rather than setting every permission on every User by hand, you define a role once (for example, Stage Manager) and assign Users to it.
Every Organization is provisioned with default Super Admin and Admin roles, which cannot be renamed or modified.
Create a UserRole
Creates a UserRole in the caller's Organization. Requires a settings.membership permission of at least CREATE. Granting a permission beyond the caller's own level is rejected with a 403; a name already used in the Organization responds 409.
Request Body
namestring · requiredDisplay name of the
UserRole(1–255 characters).authorizationobject · requiredThe permission template for this
UserRole. Same shape as aUser'sauthorization.
Responses
The newly created UserRole.
userRoleobjectA reusable permission template that
Usersinherit from.
Delete a UserRole
Deletes the specified UserRole. Requires a settings.membership permission of at least DELETE. A UserRole still assigned to one or more Users cannot be deleted, and neither can the seeded default roles (kind ≠ CUSTOM) — both respond 409.
path Parameters
userRoleIdstring · uuid · requiredThe id of the
UserRole.
Responses
The UserRole was successfully deleted.
Update a UserRole
Updates the specified UserRole. Any fields not provided remain unchanged. Requires a settings.membership permission of at least UPDATE. Granting a permission beyond the caller's own level is rejected with a 403. Responds 409 when renaming onto a name already used in the Organization, or when attempting to update a default role (kind ≠ CUSTOM); default roles cannot be renamed or modified.
path Parameters
userRoleIdstring · uuid · requiredThe id of the
UserRole.
Request Body
namestringDisplay name of the
UserRole(1–255 characters).authorizationobjectThe permission template for this
UserRole. Same shape as aUser'sauthorization.
Responses
The updated UserRole.
userRoleobjectA reusable permission template that
Usersinherit from.