V2.1 Replace Device¶

Replace the deviceKey of a device without changing its assetId. The system will override the original deviceKey and deviceSecret of the registered device, re-assign a deviceKey, generate a new deviceSecret, and reset the device to non-activated status. The new device can be connected to EnOS^TM with the replaced deviceKey, and the data of the old and new devices can be linked through the assetID.

This API is available in EnOS 2.1.0 and above. Version 2.4 has been added and it is recommended to use V2.4 Replace Device.

Operation Permissions¶

Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.

Required Service	Required Operation Permission
Device Management Service	Full Access

Prerequisite¶

You have learnt the Limitations about devices.

Request Format¶

POST https://{apigw-address}/connect-service/v2.1/devices?action=replaceDevice

Request Parameters (URI)¶

Note

Use one of the following methods to specify the device to be replaced:

Include assetId in the request
Include productKey + deviceKey in the request

Name	Location (Path/Query)	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>
assetId	Query	Optional (See Note above)	String	The asset ID. How to get assetId>>
productKey	Query	Optional (See Note above)	String	The product key. To be used with `deviceKey`.
deviceKey	Query	Optional (See Note above)	String	The device key. To be used with `productKey`.

Request Parameters (Body)¶

Name	Mandatory/Optional	Data Type	Description
newDeviceKey	Mandatory	String	The new device key of the device. Supports English letters, numbers, hyphens (-), underline (_), and dot (.). The range is 4-64 characters.

Response Parameters¶

Name	Data Type	Description
data	DeviceReplaceResult Struct	The returned results of the device replacement. For details, see DeviceReplaceResult Struct>>

DeviceReplaceResult Struct ¶

Name	Data Type	Description
assetId	String	The asset ID.
productKey	String	The product Key.
deviceKey	String	The device Key.
deviceSecret	String	The new device secret assigned by the system.

Error Codes¶

Code	Message	Description
11702	DeviceKey existed	The new device key already exists in the database.
11704	DeviceKey is repetitive	The new and old device keys are the same.
99400	Invalid arguments	One or multiple parameters are invalid.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.1/devices?action=replaceDevice&orgId=yourOrgId&assetId=yourAssetId
method: POST
requestBody:
{
    "newDeviceKey":"yourNewDeviceKey"
}

Return Sample¶

{
    "code":0,
    "msg":"OK",
    "requestId":"fa377585-8240-4d1e-ad9d-a8d820873142",
    "data":{
        "assetId":"yourAssetId",
        "productKey":"yourProductKey",
        "deviceKey":"yourNewDeviceKey",
        "deviceSecret":"yourDeviceSecret"
    }
}

SDK Samples¶

You can access the SDK samples for Connection Service on GitHub:

Java
Python