De-provisioning via Device Provisioning API

The Device Provisioning API provides a resource for de-provisioning things and policies.
If your use-case allows, we recommend to use the HTTP API directly, see https://apidocs.bosch-iot-suite.com/.

However, in this example we assume that you need to delete a thing via a live message.
When working in the context of Bosch IoT Device Management, we recommend using the Device Provisioning API, because the de-provisioning not only deletes the thing but also its associated policy, and the entities existing in Bosch IoT Hub (namely the device and its credentials).

In this example, we will create a managed connection and configure it to react on a live message to a thing, by triggering its de-provisioning via the Device Provisioning API.

Connection setup

The connection wizard of the Connections UI assists the creation of such a connection.

Select the connection category HTTP: Template for de-provisioning via Device Provisioning API.

The wizard requires the further inputs:

• Authorization subject - to define who can use this connection to receive the live messages which trigger the de-provisioning.
  The subject is pre-filled with integration:<service-instance-id>_things: , thus you only need to add a suffix.
  In general, this subject additionally needs to be set into the policy of the things.
  In our example, we set the suffix to remove and add the complete subject later to the thing’s policy.
• The Message subject: the subject of the message which triggers the de-provisioning.
  In our example we have set remove.
• The Service Instance ID is already pre-filled with the value for your subscription.
• The OAuth Token Endpoint is pre-filled to the default value.
• Set the Client ID as configured for your client.
• Set the Client secret as configured for your client.
• The Requested scopes are pre-filled to hub and things.
  
• Click Test connection, and if it works confirm creating the connection with Create.
  

The created connection is an HTTP connection which configures the Device Provisioning API as an endpoint with the given OAuth2 client credentials.

It contains a single target that is configured to trigger a DELETE request at the resource
/{service-instance-id}/devices/{device-id} , whenever it receives a live message with the specific subject.

The HTTP response received from the Device Provisioning API will be forwarded as the live message response including its response status and body.

The wizard creates a pre-configured connection, but you can of course adjust the connection to your needs before saving it, e.g. change the message subject that triggers the de-provisioning.

Adjust the policy

Use the Policy section of the thing which is to be deleted and create a separate entry for the Subject of the connection created above.

The example shows the permission to read and write messages with subject “remove” directed to the thing (i.e. inbox) as well as from the thing (i.e. outbox). However, you would only need one line, depending on the Direction you choose in the next section, where you send the message, which will in fact be used as the trigger for the de-provisioning request.

Trigger the de-provisioning

The de-provisioning is triggered by sending a live message with the configured subject to the thing that should be deleted, together with its associated policy and the entities stored in Bosch IoT Hub (device and its credentials).

This can be achieved by making a POST request to the messages resource of a thing at the Things HTTP API:
/things/{thingId}/inbox/messages/{messageSubject}, where

• {thingId} must be replaced with the ID of the thing that should be deleted, and
• {messageSubject} must be replaced with the configured live message subject.

The request body is not used and can be left empty.

The live messages can also be sent via another channel e.g. WebSocket or a different connection.