> ## Documentation Index
> Fetch the complete documentation index at: https://foreverbetter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Wearable onboarding for your users (B2B)

> How a platform connects its end-users' wearables in a streamlined, org-scoped way.

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:

| Model                                | Providers                                                                 | Where the user grants access      |
| ------------------------------------ | ------------------------------------------------------------------------- | --------------------------------- |
| ForeverBetter Connect (consumer app) | Google Health Connect, including Fitbit/Samsung Health/Google Fit sources | On-device Android app             |
| Mobile bridge (SDK)                  | Apple HealthKit, Samsung Health, Google Health Connect                    | On-device, in your own mobile app |
| Server OAuth                         | WHOOP                                                                     | Redirect 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`](https://pub.dev/packages/open_wearables_health_sdk)
Flutter plugin to your app. It handles permissions, background sync, incremental
(anchored) queries, secure token storage, and **token refresh** automatically.

```yaml theme={null}
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:

```bash theme={null}
# 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):

```bash theme={null}
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:

```bash theme={null}
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`.