Device provisioning via API

Table of contents

Simple device registration

This example shows the minimal payload required for such a request.

Your entry point into our interactive API documentation is Bosch IoT Suite - Device Provisioning.

You will need a valid JWT see Create a Suite Auth client.

Request

  1. Authorize

    1. Open the Authorization dialog.

      images/confluence/download/attachments/1172486424/auth-things-api.png
    2. Paste your Bearer token into the Value field.

    3. Confirm with Authorize.

    4. Close the dialog.

  2. Use the provisioning resource.
    POST /{service-instance-id}/devices

  3. Click Try it out to get all entry fields editable.

  4. Set the service-instance-id.
    If you have not stored your credentials at the end of the step Subscribe an Asset Communication package instance,
    open an new tab and navigate https://bosch-iot-suite.com/ > Service Subscriptions > your instance > ... Show Credentials
    copy the value of your Service Instance ID and switch back to the API docs to enter it in the respective field.

  5. Edit the content for the body.

  6. Set the minimal request body.

    • The "id" value needs to be defined by you.
      In case you have not defined a namespace yet, you will need to do it now. See First configuration steps.

    • The "hub" entries : For your credentials you can set the password in plain text here, as we use HTTPS.
      It will be stored on the backend in the hashed form.

    • The "thing" entry could theoretically remain empty (an empty "POST" thing is supported and would generate an empty thing and its default policy).

      {
      "id": "your.namespace:device-4711",
      "hub": {
      "device": { },
      "credentials": {
      "type": "hashed-password",
      "secrets": [
      {
      "password": "your-secret-in-plain-text-will-be-hashed-automatically"
      }
      ]
      }
      },
      "things": {
      "thing": {
      "attributes": {
      "manufacturer": "My awesome company"
      }
      }
      }
      }
  7. Click Execute to submit the request.

  8. Verify that the request was successful Code 201.

Response

You can download the result as JSON for further requests.

A successful response would look like the following snippet.

{
"id": "your.namespace:device-4711",
"hub": {
"credentials": {
"tenantId": "xxx_hub",
"deviceId": "your.namespace:device-4711",
"type": "hashed-password",
"authId": "your.namespace_device-4711",
"enabled": true,
"secrets": [
{
"password": "your-secret"
}
],
"adapters": [
...
]
},
"device": {
"deviceId": "your.namespace:device-4711"
}
},
"things": {
"thing": {
"attributes": {
"manufacturer": "My awesome company"
},
"thingId": "your.namespace:device-4711",
"policyId": "your.namespace:device-4711",
...
}
}
}

Please take into account that the protocol adapters of the Bosch IoT Hub have a caching mechanism in place for devices and their credentials. That means if you make changes in the device's or credentials' properties, it takes some time until the protocol adapters apply the changes. Currently the cache setting is configured to 10 minutes.

Summary

Upon success, you have created following entities: