MSP User and Role

22 operations. Call any of them with omada_call_operation (or, in full tool mode, as a tool named by its operationId).

Operation	Method	Summary
createCustomerRole	POST	Create new customer role
deleteCustomerRole	DELETE	Delete an existing customer role
modifyCustomerRole	PUT	Modify an existing customer role
getMspAppGridUsers	GET	Get msp user list for app
getAllCustomerRoles	GET	Get customer role list in msp
getMFAStatus	GET	Get the status of the MSP system's Two-Factor Authentication.
modifyMspMFAStatus	POST	Modify the status of the MSP system's Two-Factor Authentication.
getAllMspRoles	GET	Get msp role list
createNewMspRole	POST	Create new msp role
deleteMspRole	DELETE	Delete an existing msp role
getMspRole	GET	Get msp role info
modifyMspRole	PUT	Modify an existing msp role
getAvailableMspRoles	GET	Get available MSP roles for creating new user
getAvailableCustomerRoles	GET	Get available customer roles for creating new user
getGridUsers_1	GET	Get msp user list
createNewMspUser	POST	Create new msp user
deleteMspUser	DELETE	Delete an existing msp user
getUser_1	GET	Get msp user info
modifyMspUser	PUT	Modify an existing msp user
modifyMspUserBatch	PATCH	Batch modify MSP users.
getAllMspCloudUsersExcludeRoot	GET	Get all MSP cloud users exclude owner
getAllMspLocalUsersExcludeRoot	GET	Get all MSP local users exclude owner

createCustomerRole

POST /openapi/v1/msp/{mspId}/account/customer-roles

Create new customer role

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

Request body — application/json (required) — schema RoleDetailOpenApiVO

Field	Type	Required	Description
`name`	string	yes	Role name should contain 1 to 128 ASCII characters.
`type`	integer	no	Role Type should be a value as follows: 0: standard; 1: customer; 2: msp.
`defaultRole`	boolean	no	Whether role is default role.
`source`	integer	no	Role created resource. It should be a value as follows: 0: default; 1:create by standard controller or customer controller; 2: create by MSP
`privilege`	RoleVO	no	(RoleVO not expanded; call omada_get_schema "RoleVO")
`hasAllPrivilege`	boolean	no	Whether role has all site privilege.
`owner`	boolean	no	Whether role is owner.

json

// omada_call_operation
{
  "operationId": "createCustomerRole",
  "body": "{...}"
}

Details, permissions and error codes

Create new customer role
The interface requires one of the permissions:
MSP Roles Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30156 - This role already exists.
-30158 - An error occurred while creating the role.
-30161 - The number of roles has reached the limit.

deleteCustomerRole

DELETE /openapi/v1/msp/{mspId}/account/customer-roles/{roleId}

Delete an existing customer role

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`roleId`	path	string	yes	Role ID

json

// omada_call_operation
{
  "operationId": "deleteCustomerRole",
  "params": {
    "roleId": "<roleId>"
  }
}

Details, permissions and error codes

Delete an existing customer role
The interface requires one of the permissions:
MSP Roles Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30102 - This role does not exist.
-30153 - The default role cannot be deleted.
-30154 - An error occurred while deleting the role.
-30155 - The role cannot be deleted since someone has bound to it.
-30173 - The SSO bound role cannot be deleted!

modifyCustomerRole

PUT /openapi/v1/msp/{mspId}/account/customer-roles/{roleId}

Modify an existing customer role

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`roleId`	path	string	yes	Role ID

Request body — application/json (required) — schema RoleDetailOpenApiVO

Field	Type	Required	Description
`name`	string	yes	Role name should contain 1 to 128 ASCII characters.
`type`	integer	no	Role Type should be a value as follows: 0: standard; 1: customer; 2: msp.
`defaultRole`	boolean	no	Whether role is default role.
`source`	integer	no	Role created resource. It should be a value as follows: 0: default; 1:create by standard controller or customer controller; 2: create by MSP
`privilege`	RoleVO	no	(RoleVO not expanded; call omada_get_schema "RoleVO")
`hasAllPrivilege`	boolean	no	Whether role has all site privilege.
`owner`	boolean	no	Whether role is owner.

json

// omada_call_operation
{
  "operationId": "modifyCustomerRole",
  "params": {
    "roleId": "<roleId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify an existing customer role.
The interface requires one of the permissions:
MSP Roles Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30102 - This role does not exist.
-30156 - This role already exists.
-30157 - An error occurred while modifying the role.
-30159 - The default role cannot be modified.
-30162 - Cannot change the target account. An account with user management permission must have a role permission scope that covers its sub-users.

getMspAppGridUsers

GET /openapi/v1/msp/{mspId}/all-users

Get msp user list for app

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`page`	query	integer	no	Start page number. Start from 1. (default 1)
`pageSize`	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
`sorts.name`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`sorts.roleId`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`sorts.email`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`sorts.customerRoleId`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`searchKey`	query	string	no	Fuzzy query parameters, support field userName

json

// omada_call_operation
{
  "operationId": "getMspAppGridUsers"
}

Details, permissions and error codes

Get msp user list. This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
The interface requires one of the permissions:
MSP Users Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-44118 - This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.

getAllCustomerRoles

GET /openapi/v1/msp/{mspId}/customer-roles

Get customer role list in msp

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getAllCustomerRoles"
}

Details, permissions and error codes

Get customer role list in msp
The interface requires one of the permissions:
MSP Roles Manager View Only

getMFAStatus

GET /openapi/v1/msp/{mspId}/mfa/status

Get the status of the MSP system's Two-Factor Authentication.

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getMFAStatus"
}

Details, permissions and error codes

Get the status of the system's Two-Factor Authentication.
The interface requires one of the permissions:
MSP Other Settings View Only

modifyMspMFAStatus

POST /openapi/v1/msp/{mspId}/mfa/status

Modify the status of the MSP system's Two-Factor Authentication.

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

Request body — application/json (required) — schema MFAConfigOpenApiVO

Field	Type	Required	Description
`enable`	boolean	no	Whether to turn on two-factor authentication for your account

json

// omada_call_operation
{
  "operationId": "modifyMspMFAStatus",
  "body": "{...}"
}

Details, permissions and error codes

Modify the status of the system's Two-Factor Authentication.
The interface requires one of the permissions:
MSP Other Settings Modify

getAllMspRoles

GET /openapi/v1/msp/{mspId}/roles

Get msp role list

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getAllMspRoles"
}

Details, permissions and error codes

Get msp role list
The interface requires one of the permissions:
MSP Roles Manager View Only

createNewMspRole

POST /openapi/v1/msp/{mspId}/roles

Create new msp role

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

Request body — application/json (required) — schema ModifyMspRoleVO

Field	Type	Required	Description
`name`	string	yes	Role name should contain 1 to 128 ASCII characters.
`privilege`	MspRoleVO	yes	(MspRoleVO not expanded; call omada_get_schema "MspRoleVO")

json

// omada_call_operation
{
  "operationId": "createNewMspRole",
  "body": "{...}"
}

Details, permissions and error codes

Create new msp role
The interface requires one of the permissions:
MSP Roles Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30156 - This role already exists.
-30158 - An error occurred while creating the role.
-30161 - The number of roles has reached the limit.

deleteMspRole

DELETE /openapi/v1/msp/{mspId}/roles/{roleId}

Delete an existing msp role

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`roleId`	path	string	yes	Role ID

json

// omada_call_operation
{
  "operationId": "deleteMspRole",
  "params": {
    "roleId": "<roleId>"
  }
}

Details, permissions and error codes

Delete an existing msp role
The interface requires one of the permissions:
MSP Roles Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30102 - This role does not exist.
-30153 - The default role cannot be deleted.
-30154 - An error occurred while deleting the role.
-30155 - The role cannot be deleted since someone has bound to it.
-30173 - The SSO bound role cannot be deleted!

getMspRole

GET /openapi/v1/msp/{mspId}/roles/{roleId}

Get msp role info

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`roleId`	path	string	yes	Role ID

json

// omada_call_operation
{
  "operationId": "getMspRole",
  "params": {
    "roleId": "<roleId>"
  }
}

Details, permissions and error codes

Get msp role info
The interface requires one of the permissions:
MSP Roles Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30102 - This role does not exist.

modifyMspRole

PUT /openapi/v1/msp/{mspId}/roles/{roleId}

Modify an existing msp role

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`roleId`	path	string	yes	Role ID

Request body — application/json (required) — schema ModifyRoleVO

Field	Type	Required	Description
`name`	string	yes	Role name should contain 1 to 128 ASCII characters.
`privilege`	RoleVO	no	(RoleVO not expanded; call omada_get_schema "RoleVO")

json

// omada_call_operation
{
  "operationId": "modifyMspRole",
  "params": {
    "roleId": "<roleId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify an existing msp role.
The interface requires one of the permissions:
MSP Roles Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30102 - This role does not exist.
-30156 - This role already exists.
-30157 - An error occurred while modifying the role.
-30159 - The default role cannot be modified.
-30162 - Cannot change the target account. An account with user management permission must have a role permission scope that covers its sub-users.

getAvailableMspRoles

GET /openapi/v1/msp/{mspId}/roles/available

Get available MSP roles for creating new user

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getAvailableMspRoles"
}

Details, permissions and error codes

Get available MSP roles for creating new user.
The interface requires one of the permissions:
MSP Roles Manager View Only

getAvailableCustomerRoles

GET /openapi/v1/msp/{mspId}/roles/customer/roles/available

Get available customer roles for creating new user

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getAvailableCustomerRoles"
}

Details, permissions and error codes

Get available customer roles for creating new user.
The interface requires one of the permissions:
Global Roles Manager View Only

getGridUsers_1

GET /openapi/v1/msp/{mspId}/users

Get msp user list

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`page`	query	integer	no	Start page number. Start from 1. (default 1)
`pageSize`	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
`sorts.name`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`sorts.roleId`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`sorts.email`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`sorts.customerRoleId`	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
`searchKey`	query	string	no	Fuzzy query parameters, support field userName

json

// omada_call_operation
{
  "operationId": "getGridUsers_1"
}

Details, permissions and error codes

createNewMspUser

POST /openapi/v1/msp/{mspId}/users

Create new msp user

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

Request body — application/json (required) — schema CreateMspUserVO

Field	Type	Required	Description
`type`	integer	yes	Type of user should be a value as follows: 0:local user; 1: cloud user
`name`	string	yes	User name. When creating cloud user, you should set TP-LINK ID. It should contain 1 to 128 ASCII visible characters and start with letters, numbers, and underscores.
`password`	string	no	Password of local user should contain 8 to 128 ASCII visible characters.And password must be a combination of uppercase letters, lowercase letters, numbers, and special symbols. Symbols such as ! # $ % & * @ ^ are supported.
`email`	string	no	Email of user
`roleId`	string	yes	Msp role ID of user
`customerRoleId`	string	yes	Msp user's customer role ID when visit customer
`allCustomer`	boolean	yes	Whether msp user has all customer permission, including new created customer.
`customers`	array<string>	no	User customer privilege list
`alert`	boolean	no	Whether this user wants to receive alert, event, and incident emails. Make sure your email is not null.
`temporaryEnable`	boolean	no	Whether the user wants to enable the temporary worker permission
`startTime`	integer	no	The start time of the user's validity period. time range: start timestamp (Millisecond).
`endTime`	integer	no	The end time of the user's validity period. time range: end timestamp (Millisecond).

json

// omada_call_operation
{
  "operationId": "createNewMspUser",
  "body": "{...}"
}

Details, permissions and error codes

Create new msp user. This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
The interface requires one of the permissions:
MSP Users Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30103 - Invalid email address.
-30104 - Invalid username.
-30105 - Invalid password.
-30106 - This username is already registered.
-30124 - The number of users has reached the limit.
-44118 - This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.

deleteMspUser

DELETE /openapi/v1/msp/{mspId}/users/{userID}

Delete an existing msp user

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`userID`	path	string	yes	User ID

Request body — application/json (required) — schema DeleteUserVO

Field	Type	Required	Description
`forceDelete`	boolean	no	Force delete target user. If false, target user can not be deleted, when target user has child users. If true, target user will be deleted anyway. Target user's child users will be root's child user.

json

// omada_call_operation
{
  "operationId": "deleteMspUser",
  "params": {
    "userID": "<userID>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Delete an existing msp user. This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
The interface requires one of the permissions:
MSP Users Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30112 - This user does not exist.
-30114 - An error occurred while deleting the user.
-30132 - Are you sure you want to delete the account %Username%? Once deleted, all sub-users created by this account will be transferred to your account.
-44118 - This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.

getUser_1

GET /openapi/v1/msp/{mspId}/users/{userID}

Get msp user info

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`userID`	path	string	yes	User ID

json

// omada_call_operation
{
  "operationId": "getUser_1",
  "params": {
    "userID": "<userID>"
  }
}

Details, permissions and error codes

Get msp user info. This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
The interface requires one of the permissions:
MSP Users Manager View Only

modifyMspUser

PUT /openapi/v1/msp/{mspId}/users/{userID}

Modify an existing msp user

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)
`userID`	path	string	yes	User ID

Request body — application/json (required) — schema ModifyMspUserVO

Field	Type	Required	Description
`name`	string	yes	User name. When creating cloud user, you should set TP-LINK ID. It should contain 1 to 128 ASCII characters and start with letters, numbers, and underscores.
`password`	string	no	Password of local user. User can only modify his child local user's password. It should contain 8 to 128 ASCII characters.And password must be a combination of uppercase letters, lowercase letters, numbers, and special symbols. Symbols such as ! # $ % & * @ ^ are supported.
`email`	string	no	Email of user
`customerRoleId`	string	yes	Customer role ID of msp user
`allCustomer`	boolean	yes	All customers including new created customer
`customers`	array<string>	no	Customer ID list of msp user
`alert`	boolean	no	Alert email
`roleId`	string	yes	Role ID of user
`forceModify`	boolean	no	Force modify
`temporaryEnable`	boolean	no	Whether the user wants to enable the temporary worker permission
`startTime`	integer	no	The start time of the user's validity period. time range: start timestamp (Millisecond).
`endTime`	integer	no	The end time of the user's validity period. time range: end timestamp (Millisecond).

json

// omada_call_operation
{
  "operationId": "modifyMspUser",
  "params": {
    "userID": "<userID>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify an existing msp user. This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
The interface requires one of the permissions:
MSP Users Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30103 - Invalid email address.
-30104 - Invalid username.
-30105 - Invalid password.
-30106 - This username is already registered.
-30108 - This username does not exist.
-30133 - The account should not have privileges to fewer sites than its sub-users.
-30134 - Failed to add Site. Sub-users should not have privileges to more sites than their parent account.
-30135 - Are you sure you want to change the role of %Username% from Administrator to Viewer?If its role is changed, the viewer accounts it has created will be moved to your account.
-30136 - Failed to save. If the editing is saved, the viewer account will have privileges to more sites than that of its immediate superior account.
-44118 - This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.

modifyMspUserBatch

PATCH /openapi/v1/msp/{mspId}/users/batch-temporary-users

Batch modify MSP users.

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

Request body — application/json (required) — schema BatchModifyUserOpenApiVO

Field	Type	Required	Description
`userIds`	array<string>	no	The list of user IDs that need to be configured in bulk
`temporaryEnable`	boolean	no	Whether the user wants to enable the temporary worker permission
`startTime`	integer	no	The start time of the user's validity period. time range: start timestamp (Millisecond).
`endTime`	integer	no	The end time of the user's validity period. time range: end timestamp (Millisecond).

json

// omada_call_operation
{
  "operationId": "modifyMspUserBatch",
  "body": "{...}"
}

Details, permissions and error codes

Batch modify MSP users.
The interface requires one of the permissions:
MSP Users Manager Modify

getAllMspCloudUsersExcludeRoot

GET /openapi/v1/msp/{mspId}/users/cloud

Get all MSP cloud users exclude owner

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getAllMspCloudUsersExcludeRoot"
}

Details, permissions and error codes

The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30194 - This user does not exist.

getAllMspLocalUsersExcludeRoot

GET /openapi/v1/msp/{mspId}/users/local

Get all MSP local users exclude owner

Parameter	In	Type	Required	Description
`mspId`	path	string	auto	MSP ID (filled in automatically)

json

// omada_call_operation
{
  "operationId": "getAllMspLocalUsersExcludeRoot"
}

Details, permissions and error codes

The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-30194 - This user does not exist.

MSP User and Role ​

createCustomerRole ​

deleteCustomerRole ​

modifyCustomerRole ​

getMspAppGridUsers ​

getAllCustomerRoles ​

getMFAStatus ​

modifyMspMFAStatus ​

getAllMspRoles ​

createNewMspRole ​

deleteMspRole ​

getMspRole ​

modifyMspRole ​

getAvailableMspRoles ​

getAvailableCustomerRoles ​

getGridUsers_1 ​

createNewMspUser ​

deleteMspUser ​

getUser_1 ​

modifyMspUser ​

modifyMspUserBatch ​

getAllMspCloudUsersExcludeRoot ​

getAllMspLocalUsersExcludeRoot ​

MSP User and Role

createCustomerRole

deleteCustomerRole

modifyCustomerRole

getMspAppGridUsers

getAllCustomerRoles

getMFAStatus

modifyMspMFAStatus

getAllMspRoles

createNewMspRole

deleteMspRole

getMspRole

modifyMspRole

getAvailableMspRoles

getAvailableCustomerRoles

getGridUsers_1

createNewMspUser

deleteMspUser

getUser_1

modifyMspUser

modifyMspUserBatch

getAllMspCloudUsersExcludeRoot

getAllMspLocalUsersExcludeRoot