When a user first opens the app, they will need to connect to their local instance to authenticate and register the device.
Authenticating the user
The local instance can be discovered if Home Assistant has the zeroconf component configured by searching for
_home-assistant._tcp.local.. If not configured, the user will need to be asked for the local address of their instance.
When the address of the instance is known, the app will ask the user to authenticate via OAuth2 with Home Assistant. Home Assistant uses IndieAuth, which means that to be able to redirect to a url that triggers your app, you need to take some extra steps. Make sure to read the last paragraph of the "Clients" section thoroughly.
Registering the device
This requires Home Assistant 0.90 or later.
Home Assistant has a
mobile_app component that allows applications to register themselves and interact with the instance. This is a generic component to handle most common mobile application tasks. This component is extendable with custom interactions if your app needs more types of interactions than are offered by this component.
Once you have tokens to authenticate as a user, it's time to register the app with the mobile app component in Home Assistant.
First, you must ensure that the
mobile_app component is loaded. There are two ways to do this:
- You can publish a Zeroconf/Bonjour record
_hass-mobile-app._tcp.local.to trigger the automatic load of the
mobile_appcomponent. You should wait at least 60 seconds after publishing the record before continuing.
- You can ask the user to add
mobile_appto their configuration.yaml and restart Home Assistant. If the user already has
default_configin their configuration, then
mobile_appwill have been already loaded.
You can confirm the
mobile_app component has been loaded by checking the
components array of the
/api/config REST API call. If you continue to device registration and receive a 404 status code, then it most likely hasn't been loaded yet.
Registering the device
To register the device, make an authenticated POST request to
/api/mobile_app/registrations. More info on making authenticated requests.
Example payload to send to the registration endpoint:
|V||string||A unique identifier for this device. New in Home Assistant 0.104|
|V||string||A unique identifier for this app.|
|V||string||Name of the mobile app.|
|V||string||Version of the mobile app.|
|V||string||Name of the device running the app.|
|V||string||The manufacturer of the device running the app.|
|V||string||The model of the device running the app.|
|V||string||The name of the OS running the app.|
|V||string||The OS version of the device running the app.|
|V||bool||If the app supports encryption. See also the encryption section.|
|Dict||App data can be used if the app has a supporting component that extends |
When you get a 200 response, the mobile app is registered with Home Assistant. The response is a JSON document and will contain the URLs on how to interact with the Home Assistant instance. You should permanently store this information.
|string||The cloudhook URL provided by Home Assistant Cloud. Only will be provided if user is actively subscribed to Nabu Casa.|
|string||The remote UI URL provided by Home Assistant Cloud. Only will be provided if user is actively subscribed to Nabu Casa.|
|string||The secret to use for encrypted communication. Will only be included if encryption is supported by both the app and the Home Assistant instance. More info.|
|string||The webhook ID that can be used to send data back.|