Connecting to an instance

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.

Getting Ready

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_app component. You should wait at least 60 seconds after publishing the record before continuing.
  • You can ask the user to add mobile_app to their configuration.yaml and restart Home Assistant. If the user already has default_config in their configuration, then mobile_app will 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:

{
"device_id": "ABCDEFGH",
"app_id": "awesome_home",
"app_name": "Awesome Home",
"app_version": "1.2.0",
"device_name": "Robbies iPhone",
"manufacturer": "Apple, Inc.",
"model": "iPhone X",
"os_name": "iOS",
"os_version": "iOS 10.12",
"supports_encryption": true,
"app_data": {
"push_notification_key": "abcdef"
}
}
KeyRequiredTypeDescription
device_idVstringA unique identifier for this device. New in Home Assistant 0.104
app_idVstringA unique identifier for this app.
app_nameVstringName of the mobile app.
app_versionVstringVersion of the mobile app.
device_nameVstringName of the device running the app.
manufacturerVstringThe manufacturer of the device running the app.
modelVstringThe model of the device running the app.
os_nameVstringThe name of the OS running the app.
os_versionVstringThe OS version of the device running the app.
supports_encryptionVboolIf the app supports encryption. See also the encryption section.
app_dataDictApp data can be used if the app has a supporting component that extends mobile_app functionality.

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.

{
"cloudhook_url": "https://hooks.nabu.casa/randomlongstring123",
"remote_ui_url": "https://randomlongstring123.ui.nabu.casa",
"secret": "qwerty",
"webhook_id": "abcdefgh"
}
KeyTypeDescription
cloudhook_urlstringThe cloudhook URL provided by Home Assistant Cloud. Only will be provided if user is actively subscribed to Nabu Casa.
remote_ui_urlstringThe remote UI URL provided by Home Assistant Cloud. Only will be provided if user is actively subscribed to Nabu Casa.
secretstringThe 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.
webhook_idstringThe webhook ID that can be used to send data back.