Documentation is now available for the Fall 2020 Update release!

Create roles

This endpoint is used to create a partner-level or client-level role.

Leave Feedback

URL

POST https://{api-url}/api/v2/tenants/{tenantId}/roles

Sample URLs

To create a partner-level role:

https://{api-url}/api/v2/tenants/msp_6/roles

To create a client-level role:

https://{api-url}/api/v2/tenants/client_8/roles

A role defines permission sets to user and -user groups on devices and device groups. A user (or user group) can be assigned to one or more roles.

Parameters

FieldData TypeDescription
nameStringRole name.
descriptionString(Optional) Short summary describing a role.
scopeString(Optional) Define the applicability of a role.
  • Provide scope: MSP to create a partner-level role.
    Note: MSP indicates a Partner.
  • Provide scope: CLIENT  to create a client-level role.
usersString(Optional) Assign users to a role.
Note:
  • Only partner users can be assigned to a partner specific role.
  • Only client users can be assigned a client specific role.
userGroupsString(Optional) Assign role to user groups..
Note:
  • Only partner user groups can be assigned to a partner specific role.
  • Only client user groups can be assigned a client specific role.
clientsList(Optional) Configure the visibility of clients for users in a role:
  • For partner-level users: To allow users of a role to view specific clients, provide the respective client IDs.
    Note: You can also create a role without visibility of any clients.
  • For client-level users: To assign a role to specific clients, provide the respective client IDs.
devicesList(Optional) Configure the visibility of devices for users in a role: A partner and client specific roles can be created with visibility to all devices, specific devices and without any devices.
allDevicesBoolean(Optional)
  • For partner specific role: To allow all users to view all client devices for a partner, provide allDevices: true.
  • For client specific role: To allow users to view all client devices, provide allDevices: true.
deviceGroupsList(Optional) Configure the visibility of device groups.
Note: This field is applicable only to view specific devices. Provide the device group IDs of the specific client. Search Device Groups API returns the list of device groups for a tenant.
credentialSetsList(Optional) Configure visibility of credentials sets for users in a role: A partner or client specific role can be created to allow users in a role to view all credentials, specific credentials, or no credentials.
allCredentialsBoolean(Optional)
  • For partner specific role: To allow users in a role to view all credentials sets of all clients for a partner, provide allCredentials: true.
  • For client specific role: To allow users in a role to view all credential sets of all clients, provide allCredentials: true.
.
Credential sets are client-specific. To allow users in a role to view only specific credential sets, provide only the credential set IDs of the client provided in clients.
PermissionsString(Optional) Assign permission sets to a role. All users in a role would be assigned these permissions. Search Permissions Sets API is used to retrieve the list of permissions for a partner or client.

Status code

200 OK

Create a Role with Scope: MSP and Provide Visibility of Specific Clients

  • Create a role that is applicable only for partners.
  • Users in this role can view only specific clients:

Sample request

{
	"name": "Network Admin",
	"description": "Client Network Administrator",
	"scope": "MSP",
	"clients": [{
			"uniqueId": "client_8"
		},
		{
			"uniqueId": "client_9"
		}
	],
	"users": [{
			"id": "USR0000000011"
		},
		{
			"id": "USR0000000013"
		}
	],
	"userGroups": [{
			"uniqueId": "USRGRP-5dd6cb59-b4cf-083a-29f6-7f6fc2688fd3"
		},
		{
			"uniqueId": "USRGRP-98c1733f-0429-001d-8196-54a85e15d49d"
		}
	],
	"devices": [{
			"id": "49429c1c-aba5-4c1a-92c5-dd66211a5b73"
		},
		{
			"id": "ec9ac14c-c566-41da-8b61-1452357b6506"
		}
	],
	"deviceGroups": [{
			"id": "DGP-fbbabccc-578b-4658-9475-178ab034c20b"
		},
		{
			"id": "DGP-3cac84fa-1613-4035-ac23-e44c0a450a9c"
		}
	],
	"credentialSets": [{
			"uniqueId": "GxGJJk65Vr6mGUTx8uGBgMNx"
		},
		{
			"uniqueId": "y9rxRm4sMP6u5sWRKMqUu6cz"
		}
	],
	"permissions": [{
			"id": "11"
		},
		{
			"id": "13"
		}
	]
}

Sample response

{
	"uniqueId": "ROLE-0074b24b-5c0b-2332-dd99-fea506f6cebd",
	"name": "Network Admin",
	"description": "Client Network Administrator",
	"defaultRole": false,
	"clients": [{
			"uniqueId": "client_8",
			"name": "NECE Lab",
			"activated": true
		},
		{
			"uniqueId": "client_9",
			"name": "NECE Corp.",
			"activated": true
		}
	],
	"users": [{
			"id": "USR0000000011",
			"loginName": "NECEInc@opsramp.com",
			"lastName": "Inc Admin",
			"firstName": "NECE",
			"email": "john.smith@gamil.com",
			"phoneNumber": "8096250653"
		},
		{
			"id": "USR0000000013",
			"loginName": "NECEPAdmin@opsramp.com",
			"lastName": "Inc PAdmin",
			"firstName": "NECE",
			"email": "john.smith@gamil.com",
			"phoneNumber": "8096250653"
		}
	],
	"userGroups": [{
			"name": "NECE Inc Users",
			"description": "NECE Partner Users",
			"uniqueId": "USRGRP-5dd6cb59-b4cf-083a-29f6-7f6fc2688fd3"
		},
		{
			"name": "NECE Inc Escalation Users",
			"description": "NECE Inc Escalation Users",
			"uniqueId": "USRGRP-98c1733f-0429-001d-8196-54a85e15d49d"
		}
	],
	"devices": [{
			"id": "43d49023-4c47-4dbf-a59b-9c40610e1ab8",
			"generalInfo": {
				"ipAddresses": "172.24.102.169",
				"hostName": "HYDLPT044"
			},
			"clientUniqueId": "client_8",
			"type": "DEVICE"
		},
		{
			"id": "ec9ac14c-c566-41da-8b61-1452357b6506",
			"generalInfo": {
				"ipAddresses": "172.30.143.112",
				"hostName": "172.30.143.112"
			},
			"clientUniqueId": "client_9",
			"type": "DEVICE"
		}
	],
	"deviceGroups": [{
			"id": "DGP-fbbabccc-578b-4658-9475-178ab034c20b",
			"name": "Testing-dev-group",
			"description": "testing device group",
			"createdDate": "2016-10-20T07:43:48+0000",
			"updatedDate": "2016-10-20T07:43:49+0000"
		},
		{
			"id": "DGP-3cac84fa-1613-4035-ac23-e44c0a450a9c",
			"name": "Up Agent Devices",
			"description": "These are the main devices those always needs to be in up state.",
			"createdDate": "2016-12-03T17:43:05+0000",
			"updatedDate": "2016-12-05T16:00:46+0000"
		}
	],
	"credentialSets": [{
			"uniqueId": "GxGJJk65Vr6mGUTx8uGBgMNx",
			"name": "SSH",
			"secure": false,
			"port": 222,
			"snmpVersion": "V2",
			"description": "SSH Credentials",
			"autoEnableMode": false,
			"universal": true,
			"spSecure": false,
			"spPort": 0,
			"timeoutMs": 10000
		},
		{
			"uniqueId": "y9rxRm4sMP6u5sWRKMqUu6cz",
			"name": "SSH Credential for Device Loggings",
			"secure": false,
			"port": 22,
			"snmpVersion": "V2",
			"description": "SSH Credential for Device Loggings",
			"autoEnableMode": false,
			"universal": true,
			"spSecure": false,
			"spPort": 0,
			"timeoutMs": 10000
		}
	],
	"permissions": [{
			"id": 11,
			"name": "Partner Administrator",
			"description": "Partner Administrator"
		},
		{
			"id": 13,
			"name": "Dispatcher",
			"description": "Dispatcher"
		}
	]
}

Create a Role with Scope: MSP and Provide Visibility of All Clients, Devices, and Credentials

  • Create a role that applies only for a partner.
  • Users in this role can view all clients (under the partner).

Sample request

{
	"name": "Network Admin",
	"description": "Client Network Administrator",
	"scope": "MSP",
	"allClients": true,
	"allDevices": true,
	"allCredentials": true,
	"users": [{
			"id": "USR0000000011"
		},
		{
			"id": "USR0000000013"
		}
	],
	"userGroups": [{
			"uniqueId": "USRGRP-5dd6cb59-b4cf-083a-29f6-7f6fc2688fd3"
		},
		{
			"uniqueId": "USRGRP-98c1733f-0429-001d-8196-54a85e15d49d"
		}
	],
	"permissions": [{
			"id": "11"
		},
		{
			"id": "13"
		}
	]
}

Sample response

{
	"uniqueId": "ROLE-0074b24b-5c0b-2332-dd99-fea506f6cebd",
	"name": "Network Admin",
	"description": "Client Network Administrator",
	"defaultRole": false,
	"allDevices": true,
	"allCredentials": true,
	"allClients": true,
	"users": [{
			"id": "USR0000000011",
			"loginName": "NECEInc@opsramp.com",
			"lastName": "Inc Admin",
			"firstName": "NECE",
			"email": "john.smith@gamil.com",
			"phoneNumber": "8096250653"
		},
		{
			"id": "USR0000000013",
			"loginName": "NECEPAdmin@opsramp.com",
			"lastName": "Inc PAdmin",
			"firstName": "NECE",
			"email": "john.smith@gamil.com",
			"phoneNumber": "8096250653"
		}
	],
	"userGroups": [{
			"name": "NECE Inc Users",
			"description": "NECE Partner Users",
			"uniqueId": "USRGRP-5dd6cb59-b4cf-083a-29f6-7f6fc2688fd3"
		},
		{
			"name": "NECE Inc Escalation Users",
			"description": "NECE Inc Escalation Users",
			"uniqueId": "USRGRP-98c1733f-0429-001d-8196-54a85e15d49d"
		}
	],
	"permissions": [{
			"id": 11,
			"name": "Partner Administrator",
			"description": "Partner Administrator"
		},
		{
			"id": 13,
			"name": "Dispatcher",
			"description": "Dispatcher"
		}
	]
}

Create a Role with Scope: Client and Provide Visibility of All Devices and Credentials

Create a role that is applicable only for a partner:

  • Users in the role can view all clients under the partner.
  • Users in the role can view all client devices and credentials.

Sample request

{
	"name": "Network Admin client",
	"description": "Client Network Administrator",
	"allDevices": true,
	"allCredentials": true,
	"users": [{
			"id": "USR0000000014"
		},
		{
			"id": "USR0000000029"
		}
	],
	"userGroups": [{
			"uniqueId": "USRGRP-ab5afe06-0cca-9b8f-6053-357531f7d9ff"
		},
		{
			"uniqueId": "USRGRP-13cfc012-bb01-bbe3-6ed9-c46a192d0567"
		}
	],
	"permissions": [{
			"id": "14"
		},
		{
			"id": "20"
		}
	]
}

Sample response

{
	"uniqueId": "ROLE-0074b24b-5c0b-2332-dd99-fea506f6cebd",
	"name": "Network Admin client",
	"description": "Client Network Administrator",
	"defaultRole": false,
	"allDevices": true,
	"allCredentials": true,
	"clients": [{
		"id": 8,
		"uniqueId": "client_8",
		"name": "NECE Lab",
		"activated": true
	}],
	"users": [{
			"id": "USR0000000014",
			"loginName": "NECELab@opsramp.com",
			"lastName": "Lab",
			"firstName": "NECE",
			"email": "john.smith@gamil.com",
			"phoneNumber": "8096250653"
		},
		{
			"id": "USR0000000029",
			"loginName": "Admin",
			"lastName": "Admin",
			"firstName": "Client",
			"email": "test@opsramp.com",
			"phoneNumber": ""
		}
	],
	"userGroups": [{
			"name": "NECE Lab Users",
			"description": "All NECE Lab Users group",
			"uniqueId": "USRGRP-ab5afe06-0cca-9b8f-6053-357531f7d9ff"
		},
		{
			"name": "NECE Lab Escalation Users",
			"description": "All NECE lab escalation users",
			"uniqueId": "USRGRP-13cfc012-bb01-bbe3-6ed9-c46a192d0567"
		}
	],
	"permissions": [{
			"id": 14,
			"name": "IM Link Client Administrator",
			"description": "IM Link Client Administrator"
		},
		{
			"id": 20,
			"name": "Full Client Permissions",
			"description": "Full Client Permissions"
		}
	]
}

Create a Role with Scope: Client and Provide Visibility of Specific Devices, and Credentials

Create a role that is applicable for client:

  • Users in the role can view all client devices.
  • Users in the role can view all client credential sets.

Sample request

{
	"name": "Network Admin client",
	"description": "Client Network Administrator",
	"users": [{
			"id": "USR0000000014"
		},
		{
			"id": "USR0000000029"
		}
	],
	"userGroups": [{
			"uniqueId": "USRGRP-ab5afe06-0cca-9b8f-6053-357531f7d9ff"
		},
		{
			"uniqueId": "USRGRP-13cfc012-bb01-bbe3-6ed9-c46a192d0567"
		}
	],
	"devices": [{
			"id": "ad0a218d-7512-435c-9b58-614470ee8658"
		},
		{
			"id": "d628b4f1-37ad-49de-8487-43125ec3178a"
		}
	],
	"deviceGroups": [{
			"id": "DGP-876f73a7-c0e4-409c-a757-5c64205ff97a"
		},
		{
			"id": "DGP-7f2a0a45-21b2-45f9-a5d1-cb71ea990a9d"
		}
	],
	"credentialSets": [{
		"uniqueId": "GxGJJk65Vr6mGUTx8uGBgMNx"
	}, {
		"uniqueId": "SgTGcRRs9BeTbBfyXYSSnHXB"
	}],
	"permissions": [{
			"id": "20"
		},
		{
			"id": "6"
		}
	]
}

Sample response

{
	"uniqueId": "ROLE-0074b24b-5c0b-2332-dd99-fea506f6cebd",
	"name": "Network Admin client",
	"description": "Client Network Administrator",
	"defaultRole": false,
	"clients": [{
		"uniqueId": "client_8",
		"name": "NECE Lab",
		"activated": true
	}],
	"users": [{
			"id": "USR0000000014",
			"loginName": "NECELab@opsramp.com",
			"lastName": "Lab",
			"firstName": "NECE",
			"email": "john.smith@gamil.com",
			"phoneNumber": "8096250653"
		},
		{
			"id": "USR0000000029",
			"loginName": "Admin",
			"lastName": "Admin",
			"firstName": "Client",
			"email": "test@opsramp.com",
			"phoneNumber": ""
		}
	],
	"userGroups": [{
			"name": "NECE Lab Users",
			"description": "All NECE Lab Users group",
			"uniqueId": "USRGRP-ab5afe06-0cca-9b8f-6053-357531f7d9ff"
		},
		{
			"name": "NECE Lab Escalation Users",
			"description": "All NECE lab escalation users",
			"uniqueId": "USRGRP-13cfc012-bb01-bbe3-6ed9-c46a192d0567"
		}
	],
	"devices": [{
			"id": "ad0a218d-7512-435c-9b58-614470ee8658",
			"generalInfo": {
				"ipAddresses": "192.168.126.1",
				"hostName": "WORK-PC"
			},
			"clientUniqueId": "client_8",
			"type": "DEVICE"
		},
		{
			"id": "d628b4f1-37ad-49de-8487-43125ec3178a",
			"generalInfo": {
				"ipAddresses": "172.28.16.15",
				"hostName": "HYDLPT204"
			},
			"clientUniqueId": "client_8",
			"type": "DEVICE"
		}
	],
	"deviceGroups": [{
			"id": "DGP-876f73a7-c0e4-409c-a757-5c64205ff97a",
			"name": "HYD-WINDOWS",
			"description": "Windows Systems at HYD",
			"createdDate": "2016-07-24T07:27:44+0000",
			"updatedDate": "2016-07-24T07:33:15+0000"
		},
		{
			"id": "DGP-7f2a0a45-21b2-45f9-a5d1-cb71ea990a9d",
			"name": "Policy Groups",
			"createdDate": "2016-12-06T11:18:58+0000",
			"updatedDate": "2016-12-06T11:18:58+0000"
		}
	],
	"credentialSets": [{
			"uniqueId": "GxGJJk65Vr6mGUTx8uGBgMNx",
			"name": "SSH",
			"secure": false,
			"port": 222,
			"snmpVersion": "V2",
			"description": "SSH Credentials",
			"autoEnableMode": false,
			"universal": true,
			"spSecure": false,
			"spPort": 0,
			"timeoutMs": 10000
		},
		{
			"uniqueId": "SgTGcRRs9BeTbBfyXYSSnHXB",
			"id": 62,
			"name": "SSH Credential",
			"secure": false,
			"port": 22,
			"snmpVersion": "V2",
			"description": "SSH Credentails",
			"autoEnableMode": false,
			"universal": true,
			"spSecure": false,
			"spPort": 0,
			"timeoutMs": 10000
		}
	],
	"permissions": [{
			"id": 6,
			"name": "Customer",
			"description": "End customer role"
		},
		{
			"id": 20,
			"name": "Full Client Permissions",
			"description": "Full Client Permissions"
		}
	]
}