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	Explanation: 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]. Value range: The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
sign_type	Yes	Integer	Body	Explanation: 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 or 1
timestamp	Yes	String	Body	Explanation: 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 range: Fixed length: 10.
password	Yes	String	Body	Explanation: A password is the value of secret encrypted using the HMAC-SHA256 algorithm with the timestamp as the key. The device secret is returned by IoTDA upon successful device registration. Value range: Fixed length: 64.

Response Parameters

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

Parameter

Type

Description

access_token

String

Explanation:

Device token, which is used for device authentication.

Value range:

32–256 characters.

expires_in

Integer

Explanation:

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.