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 UI
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 Bosch IoT Suite.

To do so navigate to the Bosch IoT Suite UI and:

Select OAuth2 clients from the left sidebar.
Click the + button on the right.
Set a Name.
Set a Client secret.
Select the Organization Scopes. You must select only one organization scope.
Select the Service scopes.
Click Save to store the entries.

You will then be redirected to the OAuth2 clients page, where your new client will be already selected.

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

Create a token (JWT)
1. Select the Open context menu button of this particular client.
2. Click Use access token - this will generate a token (JWT) which is valid for 720 minutes.
3. In the Use access token blade that opens up from the right you can copy an access token created with your new client from Test access token.
  Keep in mind that this token is intended for testing purposes and will expire after 720 minutes.

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.

Use the HTTP API docs

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

Request

Authorize
1. Open the Authorization dialog.
2. Paste your Bearer token into the Value field.
3. Confirm with Authorize.
4. Close the dialog.
Use the provisioning resource.
POST /{service-instance-id}/devices
Click Try it out and all entry fields become editable.
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 a new tab and navigate to the Subscriptions UI feature of the Bosch IoT Suite UI, select your subscription, open its Binding credentials,
copy the value of your Service Instance ID and switch back to the API docs to enter it in the respective field.
Set the authScope to deviceManagementSubscription.
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"
  
  }
  
  }
  
  }
  
  }
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.

response example

{
  "id": "example.dm:hello-world-device-02",
  "hub": {
    "credentials": {
      "tenantId": "xxx_hub",
      "type": "hashed-password",
      "secrets": [
        {
          "password": "your-secret-in-plain-text-will-be-hashed-automatically"
        }
      ],
      "deviceId": "example.dm:hello-world-device-02",
      "authId": "example.dm_hello-world-device-02",
      "adapters": [
        {
          "type": "http",
          "uri": "https://http.bosch-iot-hub.com",
          "host": "http.bosch-iot-hub.com",
          "port": 443
        },
        {
          "type": "mqtt",
          "uri": "mqtts://mqtt.bosch-iot-hub.com",
          "host": "mqtt.bosch-iot-hub.com",
          "port": 8883
        },
        {
          "type": "amqp",
          "uri": "amqps://amqp.bosch-iot-hub.com",
          "host": "amqp.bosch-iot-hub.com",
          "port": 5671
        }
      ]
    },
    "device": {
      "deviceId": "example.dm:hello-world-device-02"
    }
  },
  "things": {
    "thing": {
      "attributes": {
        "manufacturer": "My awesome company"
      },
      "thingId": "example.dm:hello-world-device-02",
      "policyId": "example.dm:hello-world-device-02",
      "_policy": {
        "policyId": "example.dm:hello-world-device-02",
        "entries": {
          "DEVICE": {
            "subjects": {
              "integration:xxx_things:hub": {
                "type": "iot-things-integration"
              }
            },
            "resources": {
              "policy:/": {
                "grant": [
                  "READ"
                ],
                "revoke": []
              },
              "thing:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              },
              "message:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              }
            }
          },
          "DEFAULT": {
            "subjects": {
              "iot-suite:/service-instance.xxx.iot-things": {
                "type": "suite-auth"
              }
            },
            "resources": {
              "policy:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              },
              "thing:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              },
              "message:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              }
            }
          },
          "DEVICE-MANAGEMENT": {
            "subjects": {
              "iot-suite:/service-instance.xxx.iot-things@developer-console": {
                "type": "suite-auth"
              },
              "iot-suite:/service-instance.xxx.iot-things@iot-manager": {
                "type": "suite-auth"
              },
              "iot-suite:/service-instance.xxx.iot-things@iot-rollouts": {
                "type": "suite-auth"
              },
              "integration:xxx_things:iot-manager": {
                "type": "iot-things-integration"
              }
            },
            "resources": {
              "policy:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              },
              "thing:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              },
              "message:/": {
                "grant": [
                  "READ",
                  "WRITE"
                ],
                "revoke": []
              }
            }
          }
        }
      }
    }
  }
}

Result

Upon success, you have created the following entities:

A device in the context of Bosch IoT Hub, associated with credentials. Find details at 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.