User and Role

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

Operation	Method	Summary
reinvite	POST	Re-Invite an existing user
getAppGridUsers	GET	Get user list for app
getGlobalMFAStatus	GET	Get the status of the system's Two-Factor Authentication.
modifyGlobalMFAStatus	POST	Modify the status of the system's Two-Factor Authentication.
transferRoot	POST	Transfer owner permission to an existing user
getAllRoles	GET	Get role list
createNewRole	POST	Create new role
deleteRole	DELETE	Delete an existing role
getRole	GET	Get role info
modifyRole	PUT	Modify an existing role
getAvailableRole	GET	Get available roles for creating new user
getGridUsers	GET	Get user list
createNewUser	POST	Create new user
deleteUser	DELETE	Delete an existing user
getUser	GET	Get user info
modifyUser	PUT	Modify an existing user
modifyUserBatch	PATCH	Batch modify users.
getAllCloudUsersExcludeRoot	GET	Get all cloud users exclude owner
getAllLocalUsersExcludeRoot	GET	Get all local users exclude owner
transferMspRoot	POST	Transfer MSP owner permission to an existing user

reinvite

POST /openapi/v1/{omadacId}/account/users/{userID}/re-invite

Re-Invite an existing user

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
userID	path	string	yes	User ID

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

Details, permissions and error codes

Re-Invite an existing user
The interface requires one of the permissions:
Global 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):
-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.

getAppGridUsers

GET /openapi/v1/{omadacId}/all-users

Get user list for app

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada 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
searchKey	query	string	no	Fuzzy query parameters, support field userName

// omada_call_operation
{
  "operationId": "getAppGridUsers"
}

Details, permissions and error codes

Get 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:
Global 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.

getGlobalMFAStatus

GET /openapi/v1/{omadacId}/mfa/status

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

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getGlobalMFAStatus"
}

Details, permissions and error codes

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

modifyGlobalMFAStatus

POST /openapi/v1/{omadacId}/mfa/status

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

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada 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

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

Details, permissions and error codes

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

transferRoot

POST /openapi/v1/{omadacId}/owner/transfer

Transfer owner permission to an existing user

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

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

Field	Type	Required	Description
userId	string	yes	Target user ID for new owner
token	string	no	Token for transfer operation

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

Details, permissions and error codes

Only Owner of current controller can use this interface.This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
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.

getAllRoles

GET /openapi/v1/{omadacId}/roles

Get role list

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getAllRoles"
}

Details, permissions and error codes

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

createNewRole

POST /openapi/v1/{omadacId}/roles

Create new role

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

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

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

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

Details, permissions and error codes

Create new role. Only user with all permissions modify can use this interface.
The interface requires one of the permissions:
Global 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.

deleteRole

DELETE /openapi/v1/{omadacId}/roles/{roleId}

Delete an existing role

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
roleId	path	string	yes	Role ID

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

Details, permissions and error codes

Delete an existing role. Only user with all permissions modify can use this interface
The interface requires one of the permissions:
Global 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!

getRole

GET /openapi/v1/{omadacId}/roles/{roleId}

Get role info

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
roleId	path	string	yes	Role ID

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

Details, permissions and error codes

Get role info
The interface requires one of the permissions:
Global Roles Manager View Only

modifyRole

PUT /openapi/v1/{omadacId}/roles/{roleId}

Modify an existing role

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
roleId	path	string	yes	Role ID

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

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

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

Details, permissions and error codes

Modify an existing role. Only user with all permissions modify can use this interface.
The interface requires one of the permissions:
Global 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.

getAvailableRole

GET /openapi/v1/{omadacId}/roles/available

Get available roles for creating new user

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getAvailableRole"
}

Details, permissions and error codes

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

getGridUsers

GET /openapi/v1/{omadacId}/users

Get user list

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada 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
searchKey	query	string	no	Fuzzy query parameters, support field userName

// omada_call_operation
{
  "operationId": "getGridUsers"
}

Details, permissions and error codes

Get 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:
Global 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.

createNewUser

POST /openapi/v1/{omadacId}/users

Create new user

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

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

Field	Type	Required	Description
type	integer	yes	Type of user should be a value as follows: 0: local user; 1: cloud user.
roleId	string	yes	This field represents Role ID. Role can be created using 'Create new role' interface, and Role ID can be obtained from 'Get role list' interface.
name	string	yes	User name should contain 1 to 128 characters and start with letters, numbers, and underscores. When creating cloud user, you should set TP-LINK ID.
password	string	no	Password of local user should contain 8 to 128 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.
alert	boolean	no	Whether this user wants to receive alert, event, and incident emails. Make sure the email is not null.
incidentNotification	boolean	no	Incident notification, this field is deprecated, please use alert field instead.
sites	array<string>	no	User site privilege list
allSite	boolean	yes	Whether user has all site permission, including new created site.
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).
sitePrivileges	array<CreateSitePrivilegeVO>	no	User site privileges

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

Details, permissions and error codes

Create new user.
The interface requires one of the permissions:
Global 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.
-30162 - Cannot change the target account. An account with user management permission must have a role permission scope that covers its sub-users.
-30190 - You do not have the All Customers permission. Cannot grant sub-users the Modify Customers permission.
-30192 - You do not have the All Site permission. Cannot grant sub-users the Modify Sites permission.
-30196 - MSP role and customer role must be both super admin or both not super admin.
-44118 - This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
-7101 - Cloud access is not enabled.
-7106 - Bind TP-Link ID first.

deleteUser

DELETE /openapi/v1/{omadacId}/users/{userID}

Delete an existing user

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada 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.

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

Details, permissions and error codes

Delete an existing 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:
Global 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

GET /openapi/v1/{omadacId}/users/{userID}

Get user info

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
userID	path	string	yes	User ID

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

Details, permissions and error codes

Get 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:
Global 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.

modifyUser

PUT /openapi/v1/{omadacId}/users/{userID}

Modify an existing user

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
userID	path	string	yes	User ID

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

Field	Type	Required	Description
roleId	string	yes	This field represents Role ID. Role can be created using 'Create new role' interface, and Role ID can be obtained from 'Get role list' interface.
name	string	yes	User name should contain 1 to 128 characters and start with letters, numbers, and underscores. When creating cloud user, you should set TP-LINK ID.
password	string	no	Password of local user should contain 8 to 128 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
alert	boolean	no	Whether this user wants to receive alert, event, and incident emails. Make sure your email is not null.
forceModify	boolean	no	Force modify
incidentNotification	boolean	no	Incident notification, this field is deprecated, please use alert field instead.
sites	array<string>	no	User site privilege list
allSite	boolean	yes	Whether user has all site permission, including new created site.
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).
sitePrivileges	array<CreateSitePrivilegeVO>	no	User site privileges

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

Details, permissions and error codes

Modify an existing user.
The interface requires one of the permissions:
Global 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.

modifyUserBatch

PATCH /openapi/v1/{omadacId}/users/batch-temporary-users

Batch modify users.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada 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).

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

Details, permissions and error codes

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

getAllCloudUsersExcludeRoot

GET /openapi/v1/{omadacId}/users/cloud

Get all cloud users exclude owner

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getAllCloudUsersExcludeRoot"
}

Details, permissions and error codes

Get all cloud users exclude owner
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.

getAllLocalUsersExcludeRoot

GET /openapi/v1/{omadacId}/users/local

Get all local users exclude owner

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getAllLocalUsersExcludeRoot"
}

Details, permissions and error codes

Get all local users exclude owner
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.

transferMspRoot

POST /openapi/v1/msp/{mspId}/owner/transfer

Transfer MSP owner permission to an existing user

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

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

Field	Type	Required	Description
userId	string	yes	Target user ID for new owner
token	string	no	Token for transfer operation

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

Details, permissions and error codes

Transfer MSP owner permission to an existing user. Only Owner of current MSP controller can use this interface.This interface only supports the authorization code mode, not the client mode. Please call this interface in authorization code mode.
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.