Skip to main content

Security

API Key​

Partner API uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

All keys start with the xHCSAPI prefix. The expiry date is also part of the key (in UTC format).

Every API key expires after 6 months.

Every request to the API must send the API key in the x-api-key HTTP header.

curl https://<API_DOMAIN>/<RESOURCE> -H "x-api-key: <PROVIDED_API_KEY>"

API Key Renewal​

In order to automate the process of generating and distributing a new API key, it's possible to use the POST /api-keys endpoint to generate a new one.

note

Partners are responsible to manage their own API keys and ensure that they are renewed before they expire.

This is the preferred way to renew API keys, as it includes many advantages:

  • the process can be fully automated
  • reduces the risk of human error
  • does not require synchronization between Bosch Home Comfort team and partners
  • allow partners to be completely independent and autonomous to manage their own API keys

In order to use this endpoint, this request needs to be executed with an existing valid API key. If the provided key is valid, a new one will be generated and returned in the response. This key will be valid for 6 months. The old key, used to create the new one, will not be affected. It will remain valid until its expiration date. Each partner can have up to 10 valid API keys. If a partner has no valid keys, then the manual process needs to be used as a fallback.

The request takes the following form:

curl https://<API_DOMAIN>/api-keys -X POST -H "x-api-key: <VALID_API_KEY>"

More details about this endpoint can be found here

API Key Removal​

Once a new API key is generated, it remains valid until its expiration date and when expired it will not be automatically removed. In order to better manage API keys, it is possible to use the DELETE /api-keys/{keyId} endpoint to remove any API key.

note

When using the endpoint, the API key used to execute the request cannot be the same as the API key to be deleted ({keyId}); this way, it's ensured that the Partner always has at least one valid key.

This endpoint allows partners to clean up their expired API keys, remove any API key that could be compromised or simply to remove any API key that is no longer needed.

IP Whitelisting​

To ensure the security of the Partner API, the IP address used to access the API must be shared with Bosch Home Comfort Group during the onboarding process. This IP address will be whitelisted to allow access to the API.

User ID​

Partner API endpoints related to remote control actions require a user ID to be sent in the request. The user ID is used for validating the request for the given gateway based on the existing contract data, as well as for auditing on whose behalf the request is executed.

The value has to be provided in the request via the x-user-id HTTP header and always has to match the user ID in the contract (see GET /contract).

Please don't forget to inform the appliance owners, to whom the user ID belongs, to accept the latest consent version inside the Gateway Management Portal to enable the usage of the remote control endpoints via the Partner API.