Mobile app API
How an app connects to Home Assistant through the mobile_app integration. Registration, the webhook, sensors, location, notifications, and the web view.
The official companion apps talk to Home Assistant through the mobile_app integration in Core. It is a public API: any app can use it to show up in Home Assistant as a device, report sensors and location, and receive notifications. This section describes it, for people working on the official apps and for anyone building their own.
- Find and log in. The app finds the instance, and the user logs in with OAuth 2. The app gets access and refresh tokens.
- Register. With those tokens, the app registers itself with
mobile_app. Home Assistant creates a device for it, and returns a webhook ID, and optionally a secret for encryption and URLs for Home Assistant Link. - Send data. From then on, the app sends sensor updates, its location, and other requests to the webhook. Webhook requests need no token: the webhook ID is the credential.
- Receive notifications. Home Assistant pushes notifications over the WebSocket connection, or through a push service of the app.
- Show the frontend. The app shows the frontend in a web view, and hands it a token, so the user doesn't log in twice.
The companion apps architecture has the bigger picture.
- Connect and register: discovery, logging in, and the registration call.
- Send data: the webhook, its URLs, the request format, and every request type.
- Encryption: encrypting webhook traffic with libsodium.
- Sensors: registering and updating sensors, and keeping their enabled state in sync.
- Notifications: WebSocket push, cloud push, and the contract for a push server.
- Web view: showing the frontend without a second login.
The integration lives in homeassistant/components/mobile_app/ in Core:
| File | What it does |
|---|---|
http_api.py |
The registration endpoint |
webhook.py |
The webhook and most request types |
helpers.py |
Encryption and responses |
websocket_api.py |
The WebSocket push channel |
notify.py |
Sending notifications |
live_activity/ |
Live Activity tokens for iOS, and their two request types |
When the code and this documentation disagree, the code wins. Changes to the integration follow the normal Core contribution process.