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 EnOSTM 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: