Connect a Device

Start a hosted cloud-provider authorization and return the user to your application.

6 min read Updated Sep 09, 2026

Sonar manages provider authorization, token storage, refresh, and ingestion of recent and historical data. Your backend starts the connection; your frontend only opens the returned URL.

Cloud providers are the supported path today

This flow connects providers that expose a cloud API. For Apple Health, Health Connect, and Samsung Health, use the Mobile SDKs instead.

Before You Start

Create the Sonar user.
Set the user’s IANA timezone when it is known. Some providers select a regional authorization service from it.
Add your application’s HTTPS origin in Developers → Redirect origins.

A registered origin contains only a scheme, host, and optional port, for example https://app.example.com. The per-request redirect_url may include a path and query string, but its origin must be registered and it cannot contain credentials or a fragment.

Start Authorization

POST /v1/users/{id}/devices

Creates a provider authorization URL for the user.

python

response = requests.post(
    f"{BASE}/users/{user_id}/devices",
    headers=HEADERS,
    json={
        "provider": "garmin",
        "redirect_url": "https://app.example.com/settings/devices",
    },
)
response.raise_for_status()
auth_url = response.json()["auth_url"]

typescript

const response = await fetch(`${base}/users/${userId}/devices`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    provider: "garmin",
    redirect_url: "https://app.example.com/settings/devices",
  }),
});
if (!response.ok) throw new Error(await response.text());
const { auth_url } = await response.json();

json

{
  "auth_url": "https://connect.provider.example/authorization/..."
}

Send the user’s browser to auth_url. Do not fetch it from your backend: the user must complete the provider’s consent flow.

Handle the Return Redirect

Sonar appends these query parameters to your redirect_url:

Parameter	Values	Description
`status`	`success`, `error`	Authorization result
`device`	provider identifier or display name	Provider that completed the flow
`error_code`	string, only on some errors	Machine-readable connection failure

Example success:

http

https://app.example.com/settings/devices?status=success&device=garmin

Treat success as authorization, not data readiness

Ingestion continues asynchronously after the redirect. Wait for device.connected to confirm the connection, and react to each subject.synced event by fetching the resources it identifies. Historical data may arrive across multiple sync events and has no separate completion event.

Historical Data Retrieval

When a user connects a cloud provider, Sonar automatically retrieves historical data, with the default lookback period varying by provider. Extended historical retrieval may be available, subject to provider limits, user permissions, and the records available in the connected account. Contact us to discuss the historical coverage available for your use case.

Historical data becomes available progressively through the API as it is imported and processed.

Disconnect a Provider

DELETE /v1/users/{id}/devices/{provider}

Disconnects the provider, schedules its stored data for removal, and returns 204 No Content.

bash

curl -X DELETE \
  "https://atlas.sonarhealth.co/v1/users/7e4e91a5-1e4f-4fc2-903c-251046d2a4d3/devices/garmin" \
  -H "Authorization: Bearer $SONAR_API_KEY"

Unknown users and connections return 404. A successful disconnect produces a device.disconnected webhook for subscribed endpoints.

Connection Errors

Code	Status	Meaning
`invalid_redirect_url`	400	The URL is invalid or its HTTPS origin is not registered
`invalid_provider`	400	The provider slug is not supported
`invalid_timezone`	400	The profile timezone cannot select the provider’s region
`not_found`	404	The user or connection does not exist
`device_already_connected`	409	The user already has this provider connected; disconnect it first

Sandbox organizations can have at most 50 connected devices, and some plans cap connected devices on live users. If a limit is reached during provider completion, the return redirect has status=error and error_code=sandbox_device_limit_reached or error_code=live_device_limit_reached, and the provider authorization is released.