V2.4 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 only available if 2.4 Cumulative Update 1 has been applied to your environment.

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¶

The required device exists.
You have learnt the Limitations about devices.

Request Format¶

POST https://{apigw-address}/connect-service/v2.4/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.
requireSecret	Optional	Boolean	`true`: `deviceSecret` and `sessionKey` will be returned. Ensure that the RSA key pair has been created for the service account. Creating RSA Key Pairs >> `false` (default): `deviceSecret` and `sessionKey` will not be returned.

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 device secret, returned only when the value of `requireSecret` is `true`. The returned value will be encrypted. How to Decrypt >>
sessionKey	String	The key for encrypting and decrypting the value of `deviceSecret`, returned only when the value of `requireSecret` is `true`. The returned value will be encrypted. How to Decrypt >>

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.
11858	Unable to find public key	Unable to find public key for `requireSecret` due to there is no RSA key pair for the service account. Creating RSA Key Pairs >>.

Samples¶

Request Sample¶

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

Return Sample¶

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

SDK Samples¶

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

Java
Python