Bosch IoT Things HTTP API

Details regarding the syntax can be found in following sections and at the REST-like HTTP API description application itself.

tip The interactive API documentation supports you to instantly try it out.
In order to try it out please start by booking a free plan - see Book the Bosch IoT Things cloud service.
Please request a service plan as you will definitely need an identifier for each single API call.

Navigate to https://apidocs.bosch-iot-suite.com and select Bosch IoT Things - API v2 at the upper right drop-down-menu.

hings-http-api-2

Authorize

The entry point is https://apidocs.bosch-iot-suite.com

  1. Select a spec: Bosch IoT Things - API v2
  2. Servers:
    This field shows the service endpoint, which differs depending on which environment you subscribed for:
  3. Authorize - opens a pop-up-dialog with multiple options:
    • bearerAuth (http, Bearer)
      A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.
      tip
    • Alternatively you can work with a pair of API Token and user credentials:
      • Things API Token (API Key):
        • The API token must always be set, otherwise the Things service will not know that you are a legitime customer.
          Tip: The API token is not bound to a user account, nor to any thing entity representing a device, but can be used for any application interaction with our API.
        • Click Authorize.
      • User authorization - select ONE of the following options:
        • Bosch ID - OAuth2.0
          • Check the respective box in case you want to use your Bosch-ID.
          • Click Authorize.
          • You will be directed to the Bosch login dialog, and then re-directed to the Things service.
        • Basic authentication - for users provided by a Bosch IoT Permissions instance
          • Set Your-Tenant-Name\Your-Username in the username field,
          • Set the password.
          • Click Authorize.
        • Bearer Auth - JWT - for users provided by one of the external identity providers.
          • Set your complete Bearer token in the value field
          • Click Authorize.

Headers

While using the Bosch IoT Things HTTP API programmatically you will need:

  1. The header for authenticating your solution as described at Authenticate as a technical client:
    x-cr-api-token=<$your-apiToken>
  2. The header for authenticating the current user as described at Authenticate as a user:
    • via Basic Auth:
      <$tenant-name>\<$username>=<$password>
    • or alternatively with a Context ID
      (which holds for example all Groups the user is member of, and all Roles assigned to the user at the time of creating the Identity Context)
      x-im-context-id=<$the context ID>
    • or alternatively with a JSON Web Token (JWT)
      Authorization=Bearer <$ your token>
  3. The header for specifying the content type, e.g.
    Content-Type=application/json

Migration from API 1 to API 2

In case you need to migrate a thing which was created via API 1 to API 2, please note that you need to migrate the access control list entries (ACL) into a policy, and to assign your thing to such a policy.

  1. Request the thing to be migrated, via API 2 and use the field-selector to specify that the inline policy (i.e. _policy) should also be retrieved.

    GET https://things.eu-1.bosch-iot-suite.com/api/2/things/{$thingId}?fields=_policy

    Retrieve a specific Thing

  2. Create a new policy from the content of the requested inline policy, with a policyId of your choice (e.g. same as the thingId).

    PUT https://things.eu-1.bosch-iot-suite.com/api/2/policies/{$policyId}

    Create or update a Policy with a specified ID

  3. Assign the new policyId to the thing to be migrated.

    PUT https://things.eu-1.bosch-iot-suite.com/api/2/things/{$thingId}/policyId

    Create or update the Policy ID of a Thing

Note: Henceforth the thing cannot be read nor written via API 1.
Please make sure all other parts of your application (e.g. device integration, business UI) are using API 2 as well.

Imprint Legal info Privacy statement