Mobile SDK Integration Guide

​

Authentication Architecture

1. Your backend calls POST /api/v1/users/{user_id}/token and receives an access_token (valid 60 minutes) and a refresh_token.
2. Your backend forwards both tokens and the Open Wearables user_id to the app over your own authenticated API.
3. The app passes them to signIn(). The SDK stores them in the iOS Keychain / Android EncryptedSharedPreferences.
4. The SDK uploads data to POST /api/v1/sdk/users/{user_id}/sync. When the access token expires, it refreshes it on its own via POST /api/v1/token/refresh.

​

Backend Endpoint

• Create an application in the developer portal under Settings → Credentials → SDK Applications and store app_id / app_secret in your backend’s secrets. The secret is shown once.
• Create an Open Wearables user for each of your users with POST /api/v1/users and store the returned id next to your user. See User Registration.

// Express
app.post("/api/health/token", authenticateUser, async (req, res) => {
  const owUserId = req.user.owUserId; // stored when the user was created in Open Wearables

  const response = await fetch(`${process.env.OW_HOST}/api/v1/users/${owUserId}/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      app_id: process.env.OW_APP_ID,
      app_secret: process.env.OW_APP_SECRET,
    }),
  });
  if (!response.ok) {
    return res.status(502).json({ error: "Failed to create SDK token" });
  }

  const { access_token, refresh_token } = await response.json();
  res.json({ userId: owUserId, accessToken: access_token, refreshToken: refresh_token });
});

# FastAPI
@app.post("/api/health/token")
async def health_token(current_user=Depends(get_current_user)):
    ow_user_id = current_user.ow_user_id  # stored when the user was created in Open Wearables

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{os.environ['OW_HOST']}/api/v1/users/{ow_user_id}/token",
            json={"app_id": os.environ["OW_APP_ID"], "app_secret": os.environ["OW_APP_SECRET"]},
        )
    if response.status_code != 200:
        raise HTTPException(502, "Failed to create SDK token")

    data = response.json()
    return {"userId": str(ow_user_id), "accessToken": data["access_token"], "refreshToken": data["refresh_token"]}

​

SDK Lifecycle

​

Configure on every launch

​

Sign in once per user

​

Handle expired sessions

​

Select the provider (Android)

• If you don’t, the SDK picks Samsung Health whenever it is installed. Release builds can’t use Samsung Health until Samsung approves your app (see Samsung Health production requirements), so choose Health Connect unless you have that approval.
• The SDK persists the choice across restarts.
• On iOS, Apple Health is the only source and no selection is needed.

​

Request permissions

​

Start background sync

• syncDaysBack limits how much history is uploaded - from midnight that many days ago. 0 means no limit: the user’s entire history. The value is persisted until sign-out, and omitting it keeps the stored value - which is 0 if it was never set. The smallest window is 1 (since yesterday). Widening it later requires resetAnchors() while sync is stopped.
• It returns false instead of throwing when it can’t start - the SDK isn’t configured, no user is signed in, or (iOS) no types are authorized.
• There is no manual sync call. The SDK syncs in the background and resumes an interrupted sync when the app returns to the foreground.
• Track progress with getSyncStatus(). Until the first historical upload finishes, initialExportDone is false - a good moment to ask the user to keep the app open.

​

Disconnect

​

Production Checklist

​

Platform Guides