Bosch IoT Device Management

Provisioning via Device Provisioning API

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

However, in case you don't feel comfortable to use it right away, have a look on how the Developer Console does the job for you Provisioning via Developer Console
and try afterwards the steps described here.

Goal

This page first introduces you into creating an OAuth2 Client which will issue you a JWT each time you need to authenticate at the HTTP API.
Then you will learn how to execute the REST request for getting a device registered into the Hub and Things services.

Procedure

Create a Suite Auth client

Each call to our services needs to be authorized.
In this case, you will use the Suite Auth approach provided by the Bosch IoT Suite portal.

  1. Navigate to the Bosch IoT Suite portal https://accounts.bosch-iot-suite.com/subscriptions/.

  2. Click the link for OAuth2 Clients.

  3. Click + New OAuth2 Client.

    images/confluence/download/attachments/1634787991/suite-auth.png
  4. Set a Client Name.

  5. Set a Client Secret.

  6. Select the Client Scopes.

  7. Click Create to store the entries.
    images/confluence/download/attachments/1634787991/suite-auth-details.png

You may need to Refresh the page after a few seconds to see your OAuth 2 client details.

Moving forward, whenever you need a token, this client can create a new one.

Create a token (JWT)

  1. Click Use Client - this will generate a token (JWT) which is valid for 60 minutes.

  2. Click Copy to clipboard to copy the JWT to your clipboard.

Use the HTTP API docs

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

Request

  1. Authorize

    1. Open the Authorization dialog.

      images/confluence/download/attachments/1634787991/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 and all entry fields become editable.

  4. Set the service-instance-id.
    If you have not stored your credentials at the end of the step Getting started with a simple device,
    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. Set the authScope to deviceManagementSubscription.

  6. Edit the content for the body.
    Set the minimal request body.

    • The "id" value needs to be defined by you.
      Replace the first part of the ID with your namespace.
      In case you have not defined a namespace yet, you will need to do it now. See Get a namespace.
      Our example uses a namespace called "example.dm".

    • 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 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": "example.dm:hello-world-device-02",
      "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.

Response

Verify that the request was successful Code 201.

Download the result as JSON for further requests.

A successful response would look like the following snippet.

Result

Upon success, you have created the following entities:

  • A device in the context of Bosch IoT Hub, associated with credentials. Find details at Hub > device data model.

  • An empty digital twin in thing notation. For further details read Things and Features.

  • The digital twin is associated with a default policy, which will store information about who is allowed to interact with the thing. See also Policy examples.