Developer Guide
Guidelines
You are obliged to comply with our Developer Guidelines as stated in our Partner Agreement.
The Developer Guidelines consists of three parts related to Security, Branding and Application.
Please note that the Developer Guidelines, of course, cannot be exhaustive.
By applying common sense of how a functional application should work you will in general comply with our Developer Guidelines.
Please contact us in case you have any questions to our Developer Guidelines.
Security guidelines
Please ensure that your application complies with the following Security Guidelines:
- All functions have to be used carefully and efficiently to solve the envisaged objectives. A high number of requests, i.e. multiple requests per minute per device, or invalid requests may be blocked.
- Any information exchanged with the API must not be presented to the user with semantic changes.
- The user interface for the authentication/authorization of users has to be shown unmodified in a maximized web form/browser. It is not allowed to change or embed it.
- A user has to confirm any disclosure of any information gained or derived from the Bosch Smart Home to 3rd parties. For instance, forwarding Motion information detected or Alarm detected has to be explicitly confirmed by the user.
- Access and refresh tokens have to be stored in a secure way.
- Client Secret data has to be kept secret and are not be disclosed without the prior written agreement of Bosch Smart Home
- Using the API to integrate voice assistant systems (e.g. Amazon Alexa, Google Assistant) needs Bosch Smart Home’s prior written approval
Branding guidelines
You may state that your application is compatible with Bosch Smart Home Devices if this is technically correct. Please note that you may not use any Bosch Smart Home branding in the app icon, app, service or any other graphics without our written consent.
Application guidelines
Please use the event channel if you need to react to any state change. Polling for state changes shall be limited to a minimum.
Please have a look at the edgecase and implement a decommissioning process for the Bosch ID/ the Bosch Smart Home devices.
Once you have completed testing, you have the opportunity to share your work with the world!
We will review your publishing request before approving it with a certification for release to End Customers, based on the above guidelines and if performance and User experience meets our quality requirements.
Secure implementation of OAuth2 authorization code grant
Bosch smart home currently supports working with confidential OAuth2 clients [OAuth2 RFC6749 - Section 2.1] only. In order to ensure security and confidentiality of the OAuth2 client, following guidelines must be followed for implementing the OAuth2 authorization code flow.
Typical flow implemented by native apps
Requesting authorization
- A native app must not use an embedded user-agent (browser) for performing user authentication. Instead user authentication must be performed using the system browser [OAuth2 RFC8252 - Section 8.12].
- Open source libraries like AppAuth can be used for this purpose
- The client secret for the OAuth2 client must not be stored in a native app (iOS, Android, Windows etc.)
Storing access and refresh tokens
- The OAuth2 access and refresh tokens shall only be stored at the backend.
- The native app may request only the access token from the backend and hold it in memory.
- The access token refresh operation using a refresh token may only be performed by the backend.
- The backend must trigger the revocation of the refresh token by invoking the OAuth2 logout endpoint if the user does not wish to access their smart home devices and service via the native app anymore.
Access smart home devices via REST API
Bosch smart home devices and services can be accessed using the provided Bosch IoT Things REST API. Following guidelines apply for the clients that access this interface.
- The REST interface is most suitable for following types of applications (clients):
- A fire-and-forget application that executes operations on smart home devices and services but does not need to mirror the their states
- An application that mirrors the states of devices and services seldomly or only on end-user's request
- The REST interface shall not be used for polling device and service states in short intervals.
Access smart home devices via Websocket API
Bosch smart home devices and services can also be accessed over a secure websocket connection between an application and Bosch IoT Things. Following guidelines apply for the clients that access this interface.
- The Websocket interface is most suitable for following types of applications (clients):
- Application that need to mirror the states of devices and/or services in real-time
- Application that perform subsequent operations based on state change events of devices and/or services
- When using the websocket API only a single websocket channel per user should be use for all communication. This way the number of transactions can be kept to a minimum.
- An application should subscribe for state change events if and only if a subsequent operation(s) need to be performed
- For example: User 'A' wants to get informed via an Email from partner when there is movement at their home. User 'B' however does not wish to do that. In this case a subscription for motion events must only be done for user 'A' by the application.
Receive updates for smart home devices via Server-Sent Events (SSE)
In addition to the REST API and the websocket API, Bosch IoT Things also offers a SSE interface for subscribing and receiving device and service change events. Following guidelines apply for clients that access this interface:
- Usage for SSE is most suitable for following types of applications (clients):
- Application that need to mirror the states of devices and/or services in real-time but cannot work with websockets
- Application that perform subsequent operations based on state change events of devices and/or services
- SSE shall only be used in relation with the REST API.