Skip to main content
If you are building a product on ForeverBetter, your users connect their wearables from inside your app. The ForeverBetter dashboard is a developer console for connecting your own devices while testing. This guide is the production flow for onboarding many end-users. There are two connection models, both behind the generic wearables surface:
ModelProvidersWhere the user grants access
ForeverBetter Connect (consumer app)Google Health Connect, including Fitbit/Samsung Health/Google Fit sourcesOn-device Android app
Mobile bridge (SDK)Apple HealthKit, Samsung Health, Google Health ConnectOn-device, in your own mobile app
Server OAuthWHOOPRedirect from your app
Every synced source is stored scoped to (organization_id, user_id), so each of your users only ever sees their own data.

​
1. Get an organization-scoped key

Issue a Builder-or-higher API key for your organization. Mint short-lived, per-user tokens from your backend (service-account mode) so each request is scoped to the acting end-user.

​
2. Consumer Android path: ForeverBetter Connect

For a user connecting their own Android wearables, direct them to the ForeverBetter Connect app. It signs them into the same ForeverBetter account, lets them choose Google Health Connect, requests read permissions, and runs background sync. Google Health Connect can aggregate multiple Android sources, including Fitbit, Samsung Health, and Google Fit. The user flow is:
  1. Install ForeverBetter Connect from the current ForeverBetter beta or Google Play distribution.
  2. Sign in with the same email as the dashboard or agent.
  3. Choose Google Health Connect and grant the requested permissions.
  4. Start sync and wait for the first upload.
  5. Refresh the dashboard or call GET /sources before analyzing.
Google Health Connect alone is not the uploader; ForeverBetter Connect performs the account-scoped sync to https://api.foreverbetter.xyz.

​
3. Product teams: embed the SDK (HealthKit / Health Connect / Samsung)

This is the widest-coverage path and the least friction for users. Add the open_wearables_health_sdk Flutter plugin to your app. It handles permissions, background sync, incremental (anchored) queries, secure token storage, and token refresh automatically. 
dependencies:
  open_wearables_health_sdk: ^0.0.15
Flow:
  1. Your app signs the user in and obtains an access token + refresh token.
  2. The SDK requests Health Connect / HealthKit read permissions on-device.
  3. It reads new records and syncs them in the background to the wearable hub.
  4. The API reads the hub and normalizes readings under that user.
Health Connect can itself surface Fitbit, Samsung Health, and Google Fit, so one integration covers many Android sources. On the API side, nothing else is required; the data appears under GET /sources and is ready to analyze immediately.

​
4. Server OAuth: WHOOP

For WHOOP, your app initiates OAuth through the API: 
# 1. Build the authorization URL (your app redirects the user here)
curl -s "$HEALTH_API/connections/wearables/start" \
  -H "authorization: Bearer $USER_TOKEN" \
  -H "content-type: application/json" \
  -d '{"user_id":"'"$END_USER"'","organization_id":"'"$ORG"'","source_provider":"whoop","client_id":"...","redirect_uri":"https://yourapp.com/oauth/whoop"}'

# 2. Complete the connection with the returned code
curl -s "$HEALTH_API/connections/wearables/callback" \
  -H "authorization: Bearer $USER_TOKEN" \
  -H "content-type: application/json" \
  -d '{"user_id":"'"$END_USER"'","organization_id":"'"$ORG"'","source_provider":"whoop","code":"...","client_id":"...","client_secret":"...","redirect_uri":"https://yourapp.com/oauth/whoop"}'

​
5. Sync and keep tokens fresh

Pull data on a schedule (or async: true to queue it): 
curl -s "$HEALTH_API/connections/wearables/sync" \
  -H "authorization: Bearer $USER_TOKEN" \
  -H "content-type: application/json" \
  -d '{"user_id":"'"$END_USER"'","organization_id":"'"$ORG"'","provider_user_id":"...","start":"2026-06-01","end":"2026-06-30","async":true}'
WHOOP access tokens expire. Pass the refresh_token (plus client_id / client_secret) on the sync request and a 401 auto-refreshes once, returning the rotated token in refreshed_token for you to persist. You can also refresh explicitly: 
curl -s "$HEALTH_API/connections/whoop/refresh" \
  -H "authorization: Bearer $USER_TOKEN" \
  -H "content-type: application/json" \
  -d '{"refresh_token":"...","client_id":"...","client_secret":"..."}'
The mobile SDK refreshes its own tokens, so bridge users need no server-side token handling.

​
6. Use the data

Once synced, wearable data flows through the same pipeline as everything else: POST /wearables/analyze, POST /analyses (multimodal), POST /users/{id}/trends, and POST /users/{id}/health-context. Set retest and check-in cadence with GET /users/{id}/retest-reminders.