Skip to main content

​
Introduction

Open Wearables Sync SDKs enable seamless background synchronization of health data directly from Apple HealthKit (iOS), Samsung Health, and Health Connect (Android) to the Open Wearables platform. Unlike cloud-based providers (Garmin, Polar, Suunto) that use webhooks and OAuth, on-device health stores require a push-based model where data is sent from the user’s device to your backend.
Why Push-Based? Apple HealthKit, Samsung Health, and Health Connect don’t expose cloud APIs. Health data lives exclusively on the user’s device, so the mobile app must actively push data to your backend.

​
Architecture Overview

Health Data Store

Health data is stored locally on the user’s device — in Apple Health (iOS), Samsung Health, or Health Connect (Android).

Your App + Sync SDK

The SDK reads data from the health store and handles background synchronization automatically. Available as native iOS (Swift), native Android (Kotlin), or Flutter (cross-platform).

Open Wearables Platform

Data is pushed to POST {host}/api/v1/sdk/users/{userId}/sync and normalized to the unified data model.

​
Key Features

Background Sync

Health data syncs automatically even when your app is in the background, using iOS Background App Refresh or Android WorkManager.

Incremental Updates

Uses anchored queries to sync only new data since the last sync, minimizing battery usage and network traffic.

Secure Storage

Credentials stored securely in iOS Keychain or Android EncryptedSharedPreferences. API keys never leave your backend.

Wide Data Support

Steps, heart rate, workouts, sleep, body measurements, nutrition, and more — all normalized to Open Wearables data model.

​
Available SDKs

iOS (Swift)

Native iOS SDK — the core implementation for Apple HealthKit sync.

Android (Kotlin)

Native Android SDK — sync from Samsung Health and Health Connect.

Flutter

Flutter SDK — cross-platform wrapper around the native iOS and Android SDKs.

React Native

React Native SDK — cross-platform wrapper around the native iOS and Android SDKs.

​
Choosing an onboarding flow

For any real integration, use the backend token flow: your backend mints a short-lived, user-scoped token (write-only to the /sdk/* endpoints) via POST /api/v1/users/{user_id}/token and forwards it to the app over its own authenticated API. Your app_secret never touches the device. This is the standard path, covered in each platform’s Integration Guide.
Invitation codes are a niche mechanism, not a co-equal second option. They exist for apps with no backend of their own to mint and forward tokens. Right now the flow is aimed primarily at individual users self-hosting Open Wearables for their own data (and the Open Wearables app / quick manual testing), not at multi-user production integrations. If you are building your own app with its own backend, use the backend token flow above.
With an invitation code, a single-use code is issued via POST /api/v1/users/{user_id}/invitation-code - from the dashboard or the API - and the app redeems it directly against the public POST /api/v1/invitation-code/redeem to obtain SDK tokens. Two situations are possible: in the primary case the same person generates the code in their own dashboard and enters it in their own app, so it never leaves that person. A code can also be delegated - for example a coach or clinician issuing one for a client - and only in that hand-off does the code travel to someone else; when it does, use a secure channel, because the code is the sole credential (single-use blocks replay after redemption, but not first-use theft if the code is intercepted in transit).

​
Security Model

The SDK uses a secure token-based authentication flow that keeps your App credentials safe:
  1. App credentials stay on your backend - app_id and app_secret are never exposed to mobile apps
  2. Short-lived access tokens - In the standard backend token flow, generated server-to-server via POST /api/v1/users/{user_id}/token and forwarded to the mobile SDK. With the invitation code flow, the app instead redeems a single-use code at POST /api/v1/invitation-code/redeem and receives the tokens directly.
  3. Secure credential storage - iOS Keychain / Android EncryptedSharedPreferences
  4. Automatic token refresh - SDK can automatically refresh expired tokens using the refresh_token
  5. API key auth - Alternative for internal tools (not recommended for production)
Never embed your app_id / app_secret in your mobile app. Always generate access tokens on your backend and pass only the tokens to the mobile SDK.

​
Next Steps

iOS SDK

Get started with the native iOS SDK (Swift)

Android SDK

Get started with the native Android SDK (Kotlin)

Flutter SDK

Get started with the Flutter SDK