Device provisioning in the scope of an Asset Communication package subscription

In this example, we assume the thing you create needs to be "visible" for all parts of your IoT application.

The authScope field can be used and set to subscription, meaning your complete Bosch IoT Suite subscription, incl. Developer Console, Things UI, Hub service etc., will be able to access it.

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

Provisioning request

Request

  1. Authorize with a JWT (e.g. Create a Suite Auth client)

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

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

  4. Set the authScope to subscription.

  5. Set the service-instance-id.
    To look it up, open an new tab and navigate > 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.

  6. Edit the content for the body.

  7. 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-0101",
      "hub": {
      "device": { },
      "credentials": {
      "type": "hashed-password",
      "secrets": [
      {
      "password": "your-secret-in-plain-text-will-be-hashed-automatically"
      }
      ]
      }
      },
      "things": {
      "thing": {
      "attributes": {
      "manufacturer": "My awesome company"
      }
      }
      }
      }
  8. Click Execute to submit the request.

  9. Verify that the request was successful Code 201.

Response

You can download the result as JSON for further requests.

A successful created thing would look like the following snippet.

{
"thingId": "your.namespace:device-0101",
"policyId": "your.namespace:device-0101",
"attributes": {
"manufacturer": "Robert Bosch GmbH"
},
"_modified": "2020-06-05T08:59:16.798080054Z",
"_revision": 3,
"_policy": {
"policyId": "your.namespace:device-0101",
"entries": {
"DEFAULT": {
"subjects": {
"iot-suite:/service-instance.515648b1-xxx.iot-things": {
"type": "suite-auth"
}
},
"resources": {
"policy:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"thing:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"message:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
}
}
},
"DEVICE": {
"subjects": {
"integration:c7fd12e1-xxx:hub": {
"type": "iot-things-integration"
}
},
"resources": {
"thing:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"message:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
}
}
}
}
}
}

Summary

Upon success, you have created a device, and thing with a policy, which authorizes all users who have access to the same Bosch IoT Suite subscription.

The authorized subject in the DEFAULT section (see line 14 in the snippet above) is now the complete service instance.

{ "iot-suite:/service-instance.515648b1-xxx.iot-things": { "type": "suite-auth" } }

In case you omit setting the new field, the subject looks like in the following snippet.

{ "iot-suite:/service-instance.515648b1-xxx.iot-things@a785d57e-xxx": { "type": "suite-auth" } }

Check visibility

The new create thing should be visible at the Developer Console and the Things dashboard alike.

To see the all things at the Developer Console, use the "Act as application" mode.
You can find it by clicking the User icon and then authenticating with the bearer token like for the API docs.