How to use the free@home local API to access and control your smart home
The free@home local API gives you access to a free@home home automation system and lets you control and monitor it. Additionally you can create virtual devices for the system.
This API allows to query information about the current configuration of the free@home automation system including devices and their current states. There are endpoints to query and change the current state of devices, also it is possible to get updates about changes. To extend the free@home home automation system it is possible to register virtual devices in the enduser system, this can be used to have a proxy device in free@home of a real device the API user manages.
Access to the free@home local api is managed via the user management of the system access point. For this purpose, each request must be submitted with valid credentials. The system access point assigns each user account a generic username that is independent of the account name. The generated username for a specific user account can be found in the free@home next app on the settings page for the local API (More -> free@home Settings -> Local API). The credentials are transmitted according to rfc7617 via HTTP basic access authentication.
To test the api, the calls can be triggered via a web interface. This is available at http://{IP-Address of the System Access Point}/swagger.
Basic Authentication
The free@home local API makes use of the basic authentication scheme. This involves sending of a username and password with each request. This is done via an authorization header that contains a base64 encoded version of your username and password appended to the text ‘Basic’. The username and password are separated by a colon.
Example for a basic authentication header with installer as username and 12345 as password:
Authorization: Basic aW5zdGFsbGVyOjEyMzQ1