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.