Authenticating a Device

Function

This API is used to authenticate a device. Connections can be established between devices and IoTDA after successful authentication. After the authentication is successful, IoTDA returns an access token. An access token is required when APIs for property reporting and message reporting are called. If an access token expires, you need to authenticate the device again to obtain an access token. If you obtain a new access token before the old one expires, the old access token will be valid for 30 seconds before expiration.

URI

Request Method	POST
URI	/v5/device-auth
Transport Protocol	HTTPS

Request Parameters

Parameter	Mandatory	Type	Location	Description
device_id	Yes	String	Body	Device ID, which uniquely identifies a device. The value of this parameter is specified during device registration or allocated by IoTDA. If the value is allocated by the platform, the value is in the format of [product_id]_[node_id]. The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Value length: 1–128 characters
sign_type	Yes	Integer	Body	Password verification mode. 0: When the timestamp is verified using the HMAC-SHA256 algorithm, IoTDA does not check whether the message timestamp is consistent with the IoTDA time but only checks whether the password is correct. 1: When the timestamp is verified using the HMAC-SHA256 algorithm, IoTDA checks whether the message timestamp is consistent with the IoTDA time and then checks whether the password is correct. Value range: 0–1
timestamp	Yes	String	Body	The timestamp is the UTC time when the device was connected to IoTDA, in the format of YYYYMMDDHH. For example, if the UTC time is 2018/7/24 17:56:20, the timestamp is 2018072417. Value length: a fixed length of 10 characters
password	Yes	String	Body	The value of this parameter is the value of the device secret encrypted by using the HMAC-SHA256 algorithm with the timestamp as the key. The device secret is returned by IoTDA upon successful device registration. Value length: a fixed length of 64 characters

Response Parameters

Parameter	Type	Description
access_token	String	Device token, which is used for device authentication. Value length: 32–256 characters
expires_in	Integer	Remaining validity period of the authentication information, in seconds.

Parameter

Type

Description

access_token

String

Device token, which is used for device authentication.

Value length: 32–256 characters

expires_in

Integer

Remaining validity period of the authentication information, in seconds.

Example Request

POST https://{endpoint}/v5/device-auth
Content-Type: application/json

{
  "device_id" : "60a87ffebaccd902c2f1abbb_0001",
  "sign_type" : 0,
  "timestamp" : "2019120219",
  "password" : "******"
}

Example Response

Status Code: 200 OK

Content-Type: application/json

{
  "access_token" : "******",
  "expires_in" : 86399
}

Error Code

HTTP Status Code	HTTP Status Code Description	Error Code	Error Message	Error Description
400	Bad Request	IOTDA.000006	Invalid input data.	Invalid request parameters.
401	Unauthorized	IOTDA.000002	The request is unauthorized.	Authentication failed.
403	Forbidden	IOTDA.021101	Request reached the maximum rate limit.	The request frequency has reached the upper limit.
403	Forbidden	IOTDA.021102	The request rate has reached the upper limit of the tenant, limit %s.	The request frequency has reached the upper limit of the tenant.