Network Pairing Management

With the increase of network pairing methods, the Cloud Development Platform has updated the permission management APIs to provide more network pairing methods, such as Wi-Fi pairing, Bluetooth pairing, and Bluetooth + Wi-Fi dual-module pairing.

API list

Request method	API	Device type	API description
POST	/v1.0/device/paring/token	Common devices	Generate a network pairing token.
GET	/v1.0/device/paring/tokens/{token}	Common devices	Get the list of devices to be paired.
PUT	/v1.0/devices/{device_id}/enabled-sub-discovery	Zigbee devices	Open the gateway to allow the access of sub-devices.
GET	/v1.0/devices/{device_id}/list-sub	Zigbee devices	Get the list of paired devices.
GET	/v1.0/devices/{device_id}/sub-devices	Zigbee devices	Get the list of sub-devices under the gateway.

Generate a network pairing token

API description

Before the device is discovered, you need to apply for a temporary token, and perform pairing through the Tuya client SDK. After receiving the token, the device can automatically complete the discovery and account binding. It currently supports Wi-Fi paring and BLE + Wi-Fi pairing.

Note: You need to scan the device QR code to get the unique ID for the network pairing of BLE devices.

API address

POST /v1.0/device/paring/token

Request parameter

Parameter name	Data type	Parameter type	Required	Description
paring_type	String	body	Yes	Pairing types, including BLE, AP, and EZ.
uid	String	body	Yes	The unique user identifier.
time_zone_id	String	body	Yes	The ID of the user’s time zone.
home_id	String	body	No	Family ID. If left blank, it refers to the user’s default family.
extension	Object<extension>	body	No	Extension information. When the pairing type is BLE, the device UUID must be passed in.

Description of extension

Parameter name	Data type	Parameter type
uuid	String	The unique device ID.

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
expire_time	Long	The expiration time of the token
region	String	The current availability zones, including AY, EU, and US
token	String	Pairing token
secret	String	Key
extension	Object<extention>	Extension information

Note: To use the Tuya pairing SDK, you need to assemble the parameter result and set region, token, and secret as an authToken to initialize the SDK. The device will disassemble the authToken once received, and after that, you can use a token to query the pairing result.

Description of extension

Parameter name	Data type	Description
encrypt_key	String	Encryption key
random	String	Encrypted string

Request example

POST /v1.0/device/paring/token

{ "uid": "ay155********2G0fA", "time_zone_id":"Asia/Shanghai", "paring_type":"BLE", "extension":{ "uuid":"5682bceac872****" } }

Return example

{ "result": { "expire_time": 300, "extension": { "encrypt_key": "101********189f", "random": "fa2f********cb38c" }, "region": "AY", "secret": "pr_0", "token": "H73H8u7A" }, "success": true, "t": 1591257455025 }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Poll the pairing result

API description

Device pairing is an asynchronous process, and the network quality is inconsistent. As a result, the devices access the network at different time points. Therefore, the developer needs to poll the interface until the device list is queried or the timeout period is reached. The polling cycle is once per second, and the timeout period is recommended to be 100 seconds.

API address

GET /v1.0/device/paring/tokens/{token}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
token	String	URI	Yes	Device pairing token

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeed false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	Return result

Description of result

Parameter name	Data type	Description
success	Array	The list of paired devices
success.device_id	String	Device ID
success.product_id	String	Product ID
success.name	String	Device name
success.category	String	Device type
failed	Array	The list of devices failed in pairing
failed.device_id	String	Device ID
failed.code	String	Error code
failed.msg	String	Description
failed.name	String	Device name

Request example

GET /v1.0/device/paring/tokens/23sdsrsdgfd

Return example

{
    "result":{
        "failed":[

        ],
        "success":[
            {
                "category":"td",
                "device_id":"6c4b088a4116ae16c****",
                "name":"Example manufacturer",
                "product_id":"sfclyxhrfnys****"
            }
        ]
    },
    "success":true,
    "t":1591872112140
}

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Open the gateway to allow the access of sub-devices

API description

Sub-devices require a gateway to connect to the network due to its incapability of networking. When the gateway is available for network access, you can add sub-devices to the local network of the gateway to get received.

API address

PUT /v1.0/devices/{device_id}/enabled-sub-discovery

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID.
duration	Int	URL	No	Gateway discovery time. Value range: 0–3600 s. When it is set to 0, the gateway stops discovering devices. The default value is 100 seconds.

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Boolean	The returned result.

Request example

PUT /v1.0/devices/23sdsrsdgfdxxxxxx/enabled-sub-discovery?duration=100

Return example

{ "success":true, "t":1551863646940, "result":true }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Get the list of reported sub-devices

API description

Sub-device network pairing is an asynchronous process. During the process, sub-devices will join the gateway according to the number of devices and the network status. Therefore, you need to poll the API on the first discovery time to get the sub-device list. We recommend that you poll once a second until 100 seconds.

API address

GET /v1.0/devices/{device_id}/list-sub

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Gateway ID
discovery_time	Long	URL	Yes	Gateway discovery time of sub-devices, which is accurate to seconds.

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
id	String	Device number
name	String	Device name
owner_id	String	Device owner ID
active_time	Long	Device activation time
update_time	Long	Device update time
category	String	Product category
product_id	String	Product ID
online	Boolean	Online status of the device

Request example

GET /v1.0/devices/23sdsrsdgfd******/list-sub?discovery_time=1566973348

Return example

{
    "result":[
        {
            "active_time":1566973357,
            "update_time":1566973363,
            "owner_id":"5583425******",
            "product_id":"tob46aoq******",
            "name":"moke detector",
            "online":true,
            "id":"xxxxx",
            "category":"ywbj"
        }
    ],
    "t":1566973373639,
    "success":true
}

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Get the list of sub-devices under the gateway

API description

Get the list of sub-devices through the device IDs under the gateway.

API address

GET /v1.0/devices/{device_id}/sub-devices

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
id	String	ID
product_id	String	Product ID
owner_id	String	Device owner ID
online	Boolean	Online status of the device
name	String	Device name
update_time	Long	The update time of device status
active_time	Long	The last pairing time of the device
category	String	Category

Request example

GET /v1.0/devices/6ca345543******6875z88d/sub-devices

Java SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
BatchDevices batchDevices = client.gatewaySubList(devIds);

System.out.println("Get device details in batches: ");
System.out.println(JSONObject.toJSONString(batchDevices));

Return example

{
    "success":true,
    "t":1565917936198,
    "result":[
        {
            "active_time":1565857222,
            "update_time":1565857227,
            "owner_id":"52****57",
            "product_id":"Mco****jXh",
            "name":"mcs",
            "online":false,
            "id":"6cac4bd83****6875z88d",
            "category":"mcs"
        },
        {
            "active_time":1565857222,
            "update_time":1565857227,
            "owner_id":"52****57",
            "product_id":"ez****rjm",
            "name":"Example sensor",
            "online":false,
            "id":"6caabb588****0db3d7gbl",
            "category":"sj"
        }
    ]
}

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission