API Reference

Update a role

patch
https://api.controlup.com/v1/organizations//roles/

Updates an existing role by its ID.

Required permission: Manage Roles

Path Params
uuid
required
^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$

ID of your ControlUp organization. You can find your organization ID on the API Key Management page in the DEX platform.

int32
required
≥ 1

ID of the role to update. You can use GET /roles to see the ID of each role.

Body Params
string
length ≥ 1

The role’s name.

string

The role’s description.

permissions
object

A list of all permissions in the role, organized by the top-level permission category.
The permissions object also contains the scopes object which sets the device scope for the role.

The permissions and scopes for the role are overwritten with what you send in the request.
This means that to add a single permission to a role, you must send all existing permissions plus the new permission.
If you don’t send this parameter, then the permissions and scopes are unchanged.

groupsIdsToRemove
array of objects

IDs of groups to remove from the role.
You can use GET /sso-groups to see the ID of each SSO group.

groupsIdsToRemove
groupsIdsToAssign
array of objects

IDs of groups to assign to the role.
You can use GET /sso-groups to see the ID of each SSO group.

groupsIdsToAssign
usersIdsToRemove
array of objects

IDs of users to remove from the role.
You can use GET /users to see the ID of each user.

usersIdsToRemove
usersIdsToAssign
array of objects

IDs of users to assign to the role.
You can use GET /users to see the ID of each user.

usersIdsToAssign
childOrganizationIds
array of strings

Specifies the target organizations where this role is applied. This parameter is relevant only for Tenant Manager organizations.

  • If omitted or empty: The role is automatically applied to the Tenant Manager organization AND all of its child organizations.

  • If IDs are provided: The role is restricted only to the specific organization IDs listed. You can include the IDs of child organizations and/or the ID of the Tenant Manager organization itself. If you target exactly one organization ID, you can use the permissions.scopes object to further restrict permissions to specific device groups or tags within that organization.

childOrganizationIds
Responses

Updated about 2 months ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 2 months ago

Did this page help you?