Authentication and authorization
You can integrate your solutions with the Bosch IoT Things service in two ways:
- Via the HTTP API, or
- Via a Java API by using a Java client that communicates to our service via WebSocket.
On all APIs the service protects functionality and data by using
- Authentication to make sure the requestor is the one he states
- Authorization to make sure the requestor is allowed to see, use or change the information he wants to access
- Identification of your Solution whenever an API is called
User authentication at the HTTP API
A user who calls the HTTP API can be authenticated by using:
HTTP BASIC Authenticationby providing username (with tenant information) and password of users managed within the Bosch IoT Permissions service.
Identity Contextof a currently logged in user managed within the Bosch IoT Permissions service.
JSON Web Token (JWT)issued by Bosch IoT Permissions, Bosch ID or Google.
See Authenticate as a user for more details.
Technical client authentication at the HTTP API
When technical clients use the HTTP API each request must be
authenticated by using an OAuth token. The solution must
provide the signature of defined HTTP headers which are concatenated and
signed with the private key of the solution client. This signature
must be sent with each request in the HTTP header:
Authorization HTTP header, the
clientId must also be
sent, and it identifies the Solution that is executing the request.
See Authenticate as a technical client for more details.
Authentication within the Java client
When the Things service is used with the Java client, the client must be
identified and authenticated. The client is identified by its
To be able to recognize, which solution is calling the Things service, the Client ID consists of:
- The ID of the Solution which is using the Java client,
- And a custom suffix to support the usage of multiple clients per solution.
clientId = <solutionId> + ":" + <suffix>
The client authentication is implemented by either OAuth2 or a handshake using an
asymmetrical key-pair. The public key of this handshake has to be
configured at the Things service for a solution. The private key must be
kept secret by the Solution.
See Things-Client instantiation and usage for details.
Authorization is implemented with a Policy. The Policy description is located at Thing level, however it can optionally grant or revoke permissions very fine-grained at any Thing sub-resource like thing:/features/featureX/properties/propertyN.
Find details at Policies.
Solution identification on API access
Regardless which API you use or which objects you work with, you have to identify your solution when accessing the APIs. This identification is used to generally make sure that only authorized solutions can access the service.
When the service is booked, a solution ID and an API token are generated during registration. Both are used to identify the solution when the service is called via its APIs.
However, the API token and the solution ID are not sufficient to grant access to any information about data (which your solution manages within the Things service). It just grants general access to use the APIs of the service.
To prevent abuse of your service subscription treat the API token information securely and do not expose it publicly anywhere.
Depending on the authentication mechanism, the identification of your solution happens as follows:
- When using the things-client your solution is identified implicitly based on the provided clientId.
- When using a Suite authorization token your solution is implicitly identified by the service instance id contained in the access token.
- When using basic authentication with solution ID and solution secret, your solution is already identified by the provided solution ID.
- For all other authentication mechanisms you need to provide a HTTP
x-cr-api-tokenwith the value of your API token on each HTTP request.
 Authenticate a user
- Bosch JWT → Bosch ID can be used as authorized subject
- Bosch IoT Permissions → user ID, group ID, role ID, can be used as authorized subject
- Basic authentication
- Identity-context ID
- JSON Web Token (JWT)
- Google JWT → Google account ID can be used as authorized subject
 Authenticate a technical client
- OAuth2 token authentication
- Cryptographic challenge - deprecated
 Identify a solution
- API Token (HTTP header)
- Client ID
- Solution ID
- Suite authorization token