WebSocket binding

The Things Protocol message can be sent as is as WebSocket message. The Things Protocol JSON must be sent as UTF-8 encoded String payload.

The WebSocket endpoint pattern depends on which API version you use

wss://<host>/ws/1
wss://<host>/ws/2

Find the list of all endpoints at our FAQ section Environment.

When establishing a connection to the WebSocket an API token is required to send along. This can be provided via the query parameter x-cr-api-token.

wss://<host>/ws/1?x-cr-api-token={your-api-token}

User

A user who connects to the WebSocket endpoint can be authenticated by using:

  • HTTP BASIC Authentication by providing a username (with tenant information) and the password of a user managed within the Bosch IoT Permissions service.
    or
  • The Identity Context of a currently logged in user managed within the Bosch IoT Permissions service.
    or
  • A JSON Web Token (JWT) issued by the Bosch IoT Permissions service or by Google.

See Authenticate as a user for more details.

Technical client

When technical clients use the WebSocket endpoint the initial request (WebSocket upgrade) must be authenticated by using a cryptographic signature. 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: CRS clientId;algorithm;signature.

Within the 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.

As the Bosch IoT Things service is built upon the Eclipse Ditto project, the specification documented there applies accordingly.
https://www.eclipse.org/ditto/httpapi-protocol-bindings-websocket.html