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