Skip to main content

Companion app development

ApexConnect is the family of ApexOS companion apps for iOS and Android (including Wear OS). Both platforms talk to an ApexOS instance through the same server-side contract — the mobile_app integration in core — so this page is relevant whether you are hacking on the apps themselves or building something app-shaped (a custom client, a kiosk device, an automation that talks to your instance the way the apps do).

The mobile_app integration contract​

The mobile_app integration (apexos/components/mobile_app/ in core) is the server side of every companion app. The full request/response reference lives in the API section of this portal; at a high level the lifecycle is:

  1. Authenticate — the app obtains tokens via the standard OAuth flow (below).
  2. Register — the app POSTs to /api/mobile_app/registrations with its identity: app_id, app_name, app_version, device_name, manufacturer, model, os_name, and optionally device_id, os_version, a free-form app_data object, and supports_encryption. Unknown extra fields are stripped, so future app versions can send more data without breaking older cores.
  3. Get a webhook — the server responds with a generated webhook_id (and, when the app declared supports_encryption, a shared secret for NaCl SecretBox payload encryption). Registration creates a config entry on the instance, one per device.
  4. Talk over the webhook — everything afterward (location updates, sensor states, service calls) flows through /api/webhook/<webhook_id>.

On the instance, a registered app materializes as a device with device_tracker, sensor, and binary_sensor entities, a notify target, device actions, timer sync, and (on iOS) live-activity support — all implemented by the mobile_app platform modules.

OAuth client IDs at secure.auth.apexinfosys.in​

ApexOS uses an IndieAuth-style flow where the OAuth client_id is a URL the server can verify against the redirect_uri. The official app client-ID pages are served under secure.auth.apexinfosys.in, and core additionally allowlists them so app sign-in works even when the instance has no internet access:

Client IDRedirect URI(s)
https://secure.auth.apexinfosys.in/iOSapexconnect://auth-callback
https://secure.auth.apexinfosys.in/androidapexos://auth-callback, plus the Wear OS 3p_auth callbacks for in.apexinfosys.companion.android (and its .debug variant)
https://secure.auth.apexinfosys.in/dev-authapexconnect-dev://auth-callback — for development builds of the apps

If you are building a third-party client, you don't use these: host your own client-ID page on a domain you control, with your redirect_uri on the same host (or declared via a link tag on the client-ID page, per IndieAuth).

Push notifications: the relay architecture​

Native push works through a relay, since an ApexOS instance on a home network cannot reach platform push services directly:

  1. The app registers its push token. During (re-)registration it includes push_token and push_url in app_data — the two fields are inclusive, they come as a pair.
  2. The instance posts to the relay. When a notification is sent to the device's notify target, core delivers the payload to the registered push_url — the relay at pushserver.apexinfosys.in — along with the push token.
  3. The relay forwards to the device. The relay hands the message to the platform's push infrastructure, which wakes the app and shows the notification. Rate-limit information from the relay is surfaced back to the instance.

When the app has a live, local connection to the instance, notifications can instead be delivered directly over the WebSocket push channel (push_notification.py) without touching the relay at all — the relay only matters for waking a device that isn't connected.

Pointers​

  • Server-side source of truth: apexos/components/mobile_app/ in core — http_api.py (registration), webhook.py (the command surface), notify.py and push_notification.py (push).
  • Tests as documentation: tests/components/mobile_app/ shows realistic register-then-webhook exchanges for every feature.
  • API reference: the API section documents the endpoints, webhook message types, and encryption format.
  • Questions: organization discussions, or support@apexinfosys.in.