Provisioning service-阿里云帮助中心

This document provides service APIs for device provisioning and binding. You can use these APIs to implement the user binding process for Bluetooth, GPRS, and Wi-Fi devices. These APIs also include the operations required for the sub-device networking process.

Preparation before provisioning

Obtain the list of discovered devices
Filter the list of locally discovered devices

Device provisioning

Obtain a key
Connect a sub-device to a gateway
Remove the network topology of a sub-device

Device binding (Recommended)

Query device certificate information by token
Bind a device using a token (Wi-Fi, Ethernet)
Bind a device using a time window (Zigbee, cellular, Bluetooth, other)

Legacy device binding APIs (Not recommended)

Bind a Wi-Fi device
Bind a Bluetooth device
Bind a GPRS device
Bind a sub-device
Unbind a sub-device

Get the list of discovered devices

Description

Path	Version	Description	User identity authentication required
/awss/enrollee/list/get	1.0.2	Paged query for the list of discovered devices.	Yes. The client software development kit (SDK) must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
pageSize	Integer	Yes	The number of entries per page. The value must be less than or equal to 99.
pageNum	Integer	Yes	The page number. The value starts from 1.

Response parameters

Parameter	Sub-key	Type	Description
totalNum		Integer	Total number of entries.
items		JSON List	An array of objects.
	gmtCreate	Date	Creation time.
	gmtModified	Date	Modification time.
	regIotId	String	The iotId of the provisioned device.
	regProductKey	String	The ProductKey of the provisioned device.
	regDeviceName	String	The DeviceName of the provisioned device.
	regProductName	String	The product name of the provisioned device.
	enrolleeIotId	String	The iotId of the device to be provisioned.
	enrolleeProductKey	String	The ProductKey of the device to be provisioned.
	enrolleeDeviceName	String	The DeviceName of the device to be provisioned.
	enrolleeProductName	String	The product name of the device to be provisioned.
	bssid	String	Router BSSID
	ssid	String	The SSID of the hot spot.
	rssi	String	The RSSI of the hot spot.
	type	Integer	The type of the discovering device. 0: device. 1: router.
	status	Integer	The status of the provisioning process. 0: Initial. 1: Provisioning.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "pageSize": 10,
        "pageNum": 1
    }
}

Success response example

{
    "code": 200,
    "data": {
        "totalNum":12,
        "items":[
            {
                "gmtCreate":xxx,
                "gmtModified":xxx,
                "regIotId":"xxx",
                "regProductKey":"xxx",
                "regDeviceName":"xxx",
                "enrolleeIotId":"xxx",
                "enrolleeProductKey":"xxx",
                "enrolleeDeviceName":"xxx",
                "bssid":"xxx",
                "ssid":"xxx",
                "rssi":"xxx",
                "type":0,
                "status":1
            }
        ]
    },
    "message": "success"
}

Filter information for the list of locally discovered devices

Description

Path	Version	Description	User identity authentication required
/awss/enrollee/product/filter	1.0.2	Filters the list of on-premises devices discovered by the client through local communication to find devices that are not yet bound to a user. Note When you use an AppKey for the production environment, products that are under development cannot be listed. To get information about products under development, you must use an AppKey for the staging environment to send the request.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
iotDevices	JSON List	Yes	The list of information about locally discovered devices.

The `iotDevices` list is structured as follows.

Field name	Field type	Required	Detailed description
productKey	String	Yes	Product comparison
deviceName	String	Yes	The device name.

Response parameters

Parameter	Type	Description
productKey	String	The ProductKey of the product. Same as the request parameter.
deviceName	String	The device name. Same as the request parameter.
productName	String	The product name.
netType	Integer	Network type. 0: LoRa 3: Wi-Fi 4: Zigbee 5: Bluetooth 6: Cellular 7: Ethernet 8: Other
nodeType	Integer	Node type. 0: Device. 1: Gateway.
categoryKey	String	Category identifier.
categoryName	String	Category name.
categoryId	Long	The ID of the category to which the device belongs.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params":{
        "iotDevices": [{
            "productKey": "a1v12d34vm",
            "deviceName": "xxxxxx"
        },
        {
            "productKey": "a1v12d77bb",
            "deviceName": "xxxxxx"
        }]
    }
}

Success response example

{
    "code": 200,
    "data":[{
                "productKey":"a1v12d34vm",
                "deviceName":"xxxxxx",
                "netType":3,
                "nodeType":0,
                "categoryKey":"xxx",
                "categoryName":"xxx",
                "categoryId":14
            }
    ],
    "message": "success"
}

Query device certificate information by token

Description

Path	Version	Description	User identity authentication required
/awss/token/check	1.0.9	Token verification.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
token	String	Yes	The token reported by the device.
productKey	String	No	The ProductKey of the device.
deviceName	String	No	The DeviceName of the device. If this parameter is not empty, productKey cannot be empty.

Response parameters

Parameter	Type	Description
productKey	String	The ProductKey of the device to be provisioned.
deviceName	String	The DeviceName of the device to be provisioned.
iotId	String	The iotId of the device.

Examples

Request example

{
    "request": {
        "iotToken": "109049c80bxxxx62e29a3ba",
        "apiVer": "1.0.9"
    },
    "id": 1508212818676,
    "params": {
        "token":"xxx"
    },
    "version": "1.0"
}

Success response example

{
  "code": 200,
  "data": {
      "iotId": "xxxx"
      "productKey": "xxxx",
      "deviceName": "xxxx"
    },
  "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}

Error response example

{
 "code":6608,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "message":"token not found"
}

Bind a device using a token

Description

Path	Version	Description	User identity authentication required
/awss/token/user/bind	1.0.3	Verifies the token and binds the device.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	The ProductKey of the device to be provisioned.
deviceName	String	Yes	The DeviceName of the device to be provisioned.
token	String	Yes	The token reported by the device.

Response parameters

Parameter	Type	Description
data	String	The iotId of the provisioned device.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.3",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx",
        "token":"xxx"
    }
}

Success response example

{
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":"xxxxxxxxxxxxx"
}

Bind a device using a time window

Description

Path	Version	Description	User identity authentication required
/awss/time/window/user/bind	1.0.3	Verifies and binds the device within a time window of 600 seconds.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	The ProductKey of the device to be provisioned.
deviceName	String	Yes	The DeviceName of the device to be provisioned.

Response parameters

Parameter	Type	Description
data	String	The iotId of the provisioned device.

Examples

Sample request

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.3",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx"
    }
}

Sample success response

{
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":"xxxxxxxxxxxxx"
}

Get a key

Description

Path	Version	Description	User identity authentication required
/awss/cipher/get	1.0.7	Obtain a key	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Sub-key	Type	Required	Description
deviceInfoForCipher			Yes	JSON object.
	deviceName	String	Yes	deviceName
	productKey	String	Yes	The ProductKey. This parameter is required for non-Bluetooth devices but not for Bluetooth devices.
	productId	String	Yes	The productId is the hexadecimal string of the ProductKey. This parameter is required for Bluetooth devices but not for non-Bluetooth devices.
	cipherType	Integer	Yes	The type of key to generate. For more information, see the description below this table. If this parameter is empty, the default value indicates a per-product key.
	random	String	Yes	A random number. A 32-byte hexadecimal string.
	params	JSON	Yes	Extension parameters. For Bluetooth devices, you must pass the MAC address. For non-Bluetooth devices, pass an empty map.

The following describes the values of `cipherType`.

cipherType=3 Per-product key: Queries the productSecret based on the ProductKey. Key algorithm: sha256(contentByteArray).
contentByteArray=productSecret.getByte()+0x2c+hexToByte(random) 

cipherType=4 Per-device key: Queries the deviceSecret based on the ProductKey and DeviceName. Key algorithm: sha256(contentByteArray).
contentByteArray=deviceSecret.getByte()+0x2c+hexToByte(random)

cipherType=6 BLE per-product key: Key algorithm: sha256(contentByteArray).
contentByteArray=productSecret.getByte()+0x2c+hexToByte(mac)+0x2c+hexToByte(random)

cipherType=7 BLE per-device key: Key algorithm: sha256(contentByteArray).
contentByteArray=deviceSecret.getByte()+0x2c+hexToByte(mac)+0x2c+hexToByte(random)

The following describes the differences between a per-product key and a per-device key.

Per-product key: The product's key (productSecret) is used as a parameter to generate the encryption key for local communication during provisioning. In this case, you only need to provide the ProductKey.
Per-device key: The device's key (deviceSecret) is used as a parameter to generate the encryption key for local communication during provisioning. In this case, you must provide both the ProductKey and the DeviceName.

Response parameters

Name	Type	Description
secret	Integer	The encryption key used for communication during local provisioning.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "deviceInfoForCipher": {
            "deviceName": "xxxx",
           "productKey": "xxxx",
            "productId": "001e7",
            "cipherType": 3, 
            "random": "00000000000000000000000000000000",
            "params": {
                "mac":"xxx"
            }
        }
    }
}

Success response example

{
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

Connect a sub-device to a gateway

Description

Path	Version	Description	User identity authentication required
/thing/gateway/permit	1.0.2	Allows a gateway to process requests to connect sub-devices.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
iotId	String	Yes	The iotId of the gateway device.
productKey	String	Yes	The product identifier of the sub-device that is allowed to connect to the gateway.
time	Integer	Yes	The time window for connection, in seconds.

Response parameters

No business-specific response parameters.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxxxxxxxxxxx",
        "productKey": "xxxxxxxxx", 
        "time": 60                   
    }
}

Success response example

{
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":null
}

Remove the network topology of a sub-device

Description

Path	Version	Description	User identity authentication required
/thing/topo/remove	1.0.2	Removes the network topology of the sub-device.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
iotId	String	Yes	Device IoT ID
subIotid	String	Yes	The iotId of the sub-device.

Response parameters

No business-specific response parameters.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxxxxxxxxxxx",
        "subIotId": "xxxxxxxxx"                
    }
}

Success response example

{
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":null
}

Bind a Wi-Fi device

A device can be bound to a maximum of 100 users. A user can bind a maximum of 1,000 devices.

Description

path	Version	Description	User identity authentication required
/awss/enrollee/user/bind	1.0.2	Binds a Wi-Fi device.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	The ProductKey of the product to which the device belongs.
deviceName	String	Yes	Device name
token	String	Yes	The token reported by the device.

Response parameters

Name	Type	Description
iotId	String	The iotId of the bound device.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx",
        "token":"xxx"
    }
}

Success response example

{
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

Bind a Bluetooth device

Description

Path	Version	Description	User identity authentication required
/awss/ble/user/bind	1.0.2	Binds a Bluetooth device.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
deviceName	String	Yes	Device name
productId	String	Yes	The productId, which is a hexadecimal string.
sign	String	Yes	The signature. For more information, see the description below.
signMethod	String	Yes	The signature method. Supported methods: hmacSha1, hmacSha256, hmacMd5, and sha256.
signParams	JSON	Yes	Extension parameters for signing.

Note For the identity authentication of a Bluetooth device, the device passes the productId instead of the ProductKey. For signature verification, the parameters in "productKey + deviceName + map" are sorted in ascending alphabetical order and then combined into a key-value string. This string is the signature to be encrypted.

Supported signature methods (case-insensitive) are hmacSha1, hmacSha256, and hmacMd5. The signature rules are as follows:

hmac_md5(deviceSecret, clientId***deviceName***productKey***timestamp***)
hmac_sha1(deviceSecret, clientId***deviceName***productKey***timestamp***)
hmac_sha256(deviceSecret, clientId***deviceName***productKey***timestamp***)
sha256(clientId***deviceName***deviceSecret***productKey***timestamp***)

Response parameters

Name	Type	Description
iotId	String	The iotId of the Bluetooth device.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "deviceInfoForCipher": {
            "deviceName": "xxxx",
            "productId": "001e7",
            "sign": "xxxxxxx",
            "signMethod": "hmacSha1",
            "signParams": {
                "mac":"xxx"
            }
        }
    }
}

Success response example

{
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

Bind a GPRS device

Description

Path	Version	Description	User identity authentication required
/awss/gprs/user/bind	1.0.2	Binds a GPRS device.	Yes. The client SDK must enable identity.

You must bind a GPRS device within 10 minutes after it goes online. Otherwise, the binding will fail.

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	The ProductKey of the product to which the device belongs.
deviceName	String	Yes	Device Name

Response parameters

Name	Type	Description
iotId	String	The iotId of the bound device.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx"
    }
}

Success response example

{
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

Bind a sub-device

Description

Path	Version	Description	User identity authentication required
/awss/subdevice/bind	1.0.2	Binds a sub-device that is connected to a gateway.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	The ProductKey of the product to which the device belongs.
deviceName	String	Yes	Device name

Response parameters

Name	Type	Description
iotId	String	The iotId of the bound device.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx"
    }
}

Success response example

{
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

Unbind a sub-device

Description

Path	Version	Description	User identity authentication required
/awss/subdevice/unbind	1.0.2	Unbinds the current user from the specified sub-device. If the current user is the administrator of the sub-device, the network topology relationship between the sub-device and the gateway is also automatically removed.	Yes. The client SDK must enable identity authentication.

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	The ProductKey of the product to which the sub-device belongs.
deviceName	String	Yes	The DeviceName of the sub-device.

Response parameters

No business-specific response parameters.

Examples

Request example

{
    "request": {
        "iotToken": "109049c80bcde4c06b15f6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 1508212818676,
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx"
    },
    "version": "1.0"
}

Success response example

{
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":null
}