Updated on 2022-02-24 GMT+08:00

Registering a Device (Password Mode)

Typical Scenario

Before connecting a device to the IoT platform, the NA must call this API to register the device on the IoT platform and obtain the device ID and secret. Then, the device can use the device ID and secret to get authenticated and connect to the IoT platform.

This API applies to devices that use MQTT.

API Function

This API is used by an NA to register a device with the IoT platform. After registration, the device can connect to the IoT platform.

API Prototype

Method

POST

URL

https://server:port/iocm/app/reg/v2.0.0/deviceCredentials?appId={appId}

Transport Protocol

HTTPS

Request Parameters

Parameter

Mandatory or Optional

Type

Location

Description

app_key

Mandatory

String

header

Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform.

Authorization

Mandatory

String

header

Indicates the authentication information for accessing the IoT platform. The value is Bearer {accessToken}, in which {accessToken} indicates the access token returned by the Authentication API.

appId

Optional

String

query

Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform. Set this parameter to the value of appId of the authorized application.

deviceInfo

Optional

DeviceInfo

Body

Indicates the device data.

endUserId

Optional

String(256)

Body

Identifies an end user.

In the NB-IoT solution, this parameter is set to the IMSI of the device.

organization

Optional

String(256)

Body

Indicates the organization to which the device belongs.

region

Optional

String(256)

Body

Indicates the region information about a device.

timezone

Optional

String(256)

Body

Indicates the time zone where the device is located.

mqttConnect

Optional

Boolean

Body

Indicates whether the device uses MQTT for access. Set this parameter to true when registering an MQTT device.

productId

Optional

String(256)

Body

Identifies the product to which the device belongs. This parameter is used to associate the product model of the device. Either specify this parameter or the following parameters: manufacturerId, manufacturerName, deviceType, model, and protocolType.

secret

Optional

String

Body

Indicates the secret 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 IoT platform.

DeviceInfo structure

Parameter

Mandatory or Optional

Type

Location

Description

nodeId

Mandatory

String(256)

Body

Uniquely identifies a device. The value of this parameter must be the same as the device ID reported by the 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 chipset provided by the manufacturer.

  • The unique identifier of a Qualcomm chip is urn:imei:xxxx, where xxxx is the IMEI.
  • The unique identifier of a HiSilicon chip is the IMEI.
  • For details about the unique identifiers of chipsets provided by other manufacturers, contact the manufacturers.

manufacturerId

Optional

String(256)

Body

Uniquely identifies a manufacturer. This parameter, together with manufacturerName, deviceType, model, and protocolType, is used to associate the product model of the device. Either specify this parameter, manufacturerName, deviceType, model, and protocolType, or specify productId.

manufacturerName

Optional

String(256)

Body

Indicates the manufacturer name. This parameter, together with manufacturerId, deviceType, model, and protocolType, is used to associate the product model of the device. Either specify this parameter, manufacturerId, deviceType, model, and protocolType, or specify productId.

deviceType

Optional

String(256)

Body

Indicates the device type. The upper camel case is used, for example, MultiSensor, ContactSensor, and CameraGateway.

This parameter, together with manufacturerId, manufacturerName, model, and protocolType, is used to associate the product model of the device. Either specify this parameter, manufacturerId, manufacturerName, model, and protocolType, or specify productId.

model

Mandatory

String(256)

Body

Indicates the device model. This parameter, together with manufacturerId, manufacturerName, deviceType, and model, is used to associate the product model of the device. Either specify this parameter, manufacturerId, manufacturerName, deviceType, and model, or specify productId.

protocolType

Optional

String(256)

Body

Indicates the protocol used by the device. MQTT is supported.

This parameter, together with manufacturerId, manufacturerName, deviceType, and model, is used to associate the product model of the device. Either specify this parameter, manufacturerId, manufacturerName, deviceType, and model, or specify productId.

name

Optional

String

Body

Indicates the device name.

Response Parameters

Status Code: 200 OK

Parameter

Type

Description

deviceId

String(256)

Uniquely identifies a device. The value of this parameter is allocated by the IoT platform during device registration.

psk

String(32)

Indicates a random PSK generated by the IoT platform.

secret

String(256)

Indicates the device secret, with which the device can get authenticated and connect to the IoT 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 IoT platform.

Request Example

Method: POST
request:
https://server:port/iocm/app/reg/v2.0.0/deviceCredentials?appId=*********
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
Body:
{
  "deviceInfo": {
    "nodeId": "******",
    "manufacturerName": "******",
    "manufacturerId": "******",
    "deviceType": "******",
    "model": "******",
    "protocolType": "******",
    "name": "******"
  },
  "endUserId": "***********",
  "organization": "***********",
  "region": "***********",
  "timezone": "***********",
  "mqttConnect": true,
  "productId": "***********",
  "secret": "***********"
}

Response Example

response:
Status Code: 200 OK
Content-Type: application/json
Body:
{
  "deviceId": "*******",
  "psk": "*********",
  "secret": "*********"
}

Error Codes

HTTP Status Code

Error Code

Error Description

Remarks

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 nodeId is duplicated.

The value of nodeId is duplicated.

Recommended handling: Check whether nodeId carried in the API request is correct.

400

50400

The input is invalid.

An input parameter is invalid.

Recommended handling: Check whether parameters carried in the API call request are valid.

403

100203

The application is not existed.

The application does not exist.

Recommended handling:

  • Check whether appId carried in the HTTP request header is correct.
  • Check whether appId in the request path (URL) is correct.

403

100217

The application hasn't 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

app throttle exceed.

The NA 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

App_key or access_token is invalid.

The access token is invalid.

Recommended handling: Check whether accessToken carried in the API request is correct.

403

600002

The product not existed.

The product does not exist.

Recommended handling: Check whether productId is correct.

500

100001

Internal server error.

An internal server error occurs.

Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.

500

100203

The application is not existed.

The authorized application does not exist.

Recommended handling:

  • Check whether appId carried in the HTTP request header is correct.
  • Check whether appId in the request path (URL) is correct.

500

100412

The amount of device has reached the limit.

The number of devices under the current application reaches the upper limit.

Recommended handling: Check whether the number of devices under the current application reaches the upper limit.

500

103026

The license is not exist.

The license does not exist.

Recommended handling: An internal license error occurs on the IoT platform. Contact IoT platform maintenance personnel.

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.