Create a role

post

https://api.controlup.com/v1/organizations/{orgId}/roles

Creates a new role.

Required permission: Manage Roles

Path Params

orgId

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.

Body Params

name

string

required

length ≥ 1

The role’s name.

description

string

The role’s description.

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

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.

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

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

Responses

200Ok

400Bad Request

401Unauthorized: Access is denied

403Forbidden: Access to this resource is denied

404Not Found: The requested resource could not be found

500Internal Server Error