Connect a Device

The Quickstart uses sandbox seed data — pre-loaded metrics and scores that let you explore the API without a device. To get real data, you connect a wearable. Sonar supports two connection paths depending on the device type.

Two Connection Paths

Mobile SDK

The Mobile SDK reads directly from the on-device health store. It handles OS permissions, background syncing, and data upload — your app just needs to initialize it.

Your backend generates a short-lived, single-use mobile token scoped to one user, then passes it to your app. This is the only API call involved — your API key stays on your server.

import requests

BASE = "https://api.sonarhealth.co/v1"
HEADERS = {"Authorization": "Bearer sk_sandbox_abc123", "Content-Type": "application/json"}

resp = requests.post(f"{BASE}/auth/mobile-token", headers=HEADERS, json={
    "user_id": "usr_abc123",  # the Sonar user from the Quickstart
})
token = resp.json()["token"]
# Return this token to your mobile app via your own API

const BASE = "https://api.sonarhealth.co/v1";
const HEADERS = {
  Authorization: "Bearer sk_sandbox_abc123",
  "Content-Type": "application/json",
};

const { token } = await fetch(`${BASE}/auth/mobile-token`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ user_id: "usr_abc123" }), // the Sonar user from the Quickstart
}).then(r => r.json());
// Return this token to your mobile app via your own API

Your app passes the token to the SDK, which prompts the user for health data permissions and begins syncing in the background. The token expires in 5 minutes — generate a fresh one each time the user opens your app or reconnects.

Once the user grants permissions, data syncs automatically — no further code required on the mobile side. The SDK handles two types of sync:

• Incremental sync — runs automatically in the background, pulling new data since the last sync
• Historical backfill — imports existing data from the health store, up to 2 years back depending on the range you request

By default both run automatically on init. For more control, you can separate them — start incremental sync immediately to show today's data fast, then trigger backfill on your own schedule (e.g., after onboarding, on WiFi, or behind a progress indicator). See the platform SDK guides for details.

Cloud API

The Cloud API connects devices through OAuth — but Sonar manages the entire OAuth exchange. You generate a connection URL, send the user there, and Sonar handles authorization, token exchange, and data ingestion. No mobile app, no callback endpoint, no OAuth infrastructure on your side.

Generate a connection URL for the provider you want to connect. Sonar returns an auth_url — share it with your user however fits your product (redirect, email, in-app link):

resp = requests.post(f"{BASE}/users/usr_abc123/devices", headers=HEADERS, json={
    "provider": "garmin",
})
auth_url = resp.json()["data"]["auth_url"]
# Send this URL to your user — redirect, email, in-app link, etc.

const { data } = await fetch(`${BASE}/users/usr_abc123/devices`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ provider: "garmin" }),
}).then(r => r.json());
// Send data.auth_url to your user — redirect, email, in-app link, etc.

The user visits the URL, sees the device manufacturer's consent screen (e.g., Garmin Connect), and authorizes. The OAuth callback goes to Sonar — Sonar exchanges the code, stores the credentials, and starts pulling data. You can optionally pass a redirect_url to land the user back in your app after they authorize.

What to Expect

Regardless of which path you use, data flows through the same API endpoints you used in the Quickstart.

Health scores start computing after 24 hours of data, but score_status transitions from calibrating to ready after 3–4 days of continuous wear. See Health Scores for timelines per score type.

Multiple devices can coexist on the same user — an Apple Watch via SDK and an Oura Ring via Cloud API, for example. Sonar deduplicates automatically. See Data Model — Multi-Device Deduplication for how priority works.

Ongoing syncing is automatic. In production, use webhooks to know exactly when new data arrives instead of polling.

Go Deeper