Refreshing a Device Secret
Typical Scenario
If the node ID of a device that has been registered with the platform changes (for example, a device is replaced), an application needs to call this API to update the node ID of the device and rebind the device.
The device secret can be updated only when the device is offline.
API Function
This API is used by an application to update the node ID of a device that has been registered with the platform, and rebind the device with the device ID unchanged.
API Description
1 | RefreshDeviceKeyOutDTO refreshDeviceKey(RefreshDeviceKeyInDTO rdkInDTO, String deviceId, String appId, String accessToken) throws NorthApiException
|
Class
DeviceManagement
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| deviceId | Mandatory | String(256) | path | Identifies a device. The device ID is allocated by the platform during device registration. |
| appId | Mandatory | String | query | If the device belongs to the current application, set this parameter to null. Otherwise, set this parameter to the ID of the authorized application. |
| accessToken | Mandatory | String | header | If the Periodically Refreshing a Token API is called, set this parameter to null. Otherwise, set this parameter to the accessToken obtained by the Authentication API. |
| rdkInDTO | Mandatory | RefreshDeviceKeyInDTO | body | For details, see RefreshDeviceKeyInDTO structure. |
RefreshDeviceKeyInDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| verifyCode | Optional | String(256) | body | Indicates the verification code of the device. If this parameter is specified in the request, it is returned in the response. If this parameter is not specified in the request, it is automatically generated by the platform. You are advised to set this parameter to the value of nodeId. |
| nodeId | Optional | String(256) | body | Uniquely identifies a device. Generally, the MAC address, serial number, or IMEI is used as the node ID.
NOTE: When the IMEI is used as the node ID, the node ID varies depending on the chip provided by the manufacturer.
|
| timeout | Optional | Integer | body | Indicates the validity period of the verification code, in units of seconds. The value is an integer greater than or equal to 0.
|
Return Value
RefreshDeviceKeyOutDTO structure
| Parameter | Type | Description |
|---|---|---|
| verifyCode | String(256) | Indicates the device verification code, with which the device can get authenticated and connect to the platform. If this parameter is specified in the request, it is returned in the response. If this parameter is not specified in the request, it is automatically generated by the platform. |
| timeout | Integer | Indicates the validity period of the verification code, in seconds. The device must connect to the platform within this period. |
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 200 | 100217 | The application has not been authorized. | The application has not been authorized. Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null. |
| 400 | 100003 | Invalid verification code. | The verification code is invalid. Recommended handling: Check whether verifyCode carried in the API request is correct. If verifyCode is not carried in the API request, contact IoT platform maintenance personnel. |
| 400 | 100007 | Bad request message. | The request message contains invalid parameters. Recommended handling: The value of deviceId is not assigned. Set this parameter based on the description of request parameters. |
| 400 | 100426 | The node ID is duplicated. | The value of nodeId is duplicated. Recommended handling: Check whether nodeId carried in the API request is correct. |
| 400 | 100610 | The device has not been activated. | The device has not been activated. Recommended handling: Check whether the device has been connected to the IoT platform and activated. |
| 400 | 100611 | The device is online. | The device is online. Recommended handling: Enable the device to go offline or disconnect the device from the IoT platform. |
| 400 | 50400 | An input parameter is invalid. | An input parameter is invalid. Recommended handling: Check whether parameters carried in the API call request are valid. |
| 401 | 100025 | The application ID used for authentication does not exist. | The application ID used for authentication does not exist. Recommended handling:
|
| 403 | 100203 | The application does not exist. | The authorized application does not exist. Recommended handling:
|
| 403 | 100217 | The application has not been authorized. | The application has not been authorized. Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null. |
| 403 | 1010009 | The application calls the API at a frequency that exceeds the flow control threshold. | The application calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default). Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency. |
| 403 | 1010005 | Invalid access token or application ID. | The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct. |
| 404 | 100403 | The device does not exist. | The device does not exist. Recommended handling: Check whether deviceId is correct. |
| 404 | 100418 | The device data does not exist. | The device data does not exist. Recommended handling:
|
| 500 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 500 | 50252 | Internal server error. | An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
Last Article: Registering a Device (Verification Code Mode)
Next Article: Modifying Device Information
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.