Skip to main content
Need help with your Sensor Bio integration? Pop into our Discord if you have questions or want to discover how Open Wearables can solve your problems.

​
Overview

Sensor Bio provides access to workout, sleep, recovery, and continuous biometric data through their REST API. The integration uses OAuth 2.0 for authentication and pull-based syncing. All API requests use HTTP/2 as required by the Sensor Bio API specification.

​
Supported data types

​
Data delivery

​
Provider quirks

Sensor Bio delivers biometric data (heart rate, HRV, SpO2, respiratory rate) as a continuous stream via the /v1/biometrics endpoint using cursor-based pagination (last-timestamp). Unlike day-aggregated providers, each poll window can return hundreds of timestamped samples covering arbitrary time ranges.
  • Timestamps in the biometrics timeseries are milliseconds since epoch.
  • Sleep endpoint timestamps (start_timestamp, end_timestamp) are seconds since epoch (not milliseconds — the API docs are inconsistent; the implementation follows observed behavior).
  • The cursor stops when the links.next field is absent or the last record timestamp is unchanged.

​
Prerequisites

  • A Sensor Bio developer account with API access
  • SENSORBIO_CLIENT_ID and SENSORBIO_CLIENT_SECRET environment variables set (see .env.example)
  • SENSORBIO_REDIRECT_URI must match the redirect URI registered in the Sensor Bio developer portal

​
Environment variables

​
OAuth flow

The integration follows the standard OAuth 2.0 authorization code flow:
  1. User initiates connection — Open Wearables redirects to https://api.sensorbio.com/oauth/authorize
  2. User grants consent in the Sensor Bio app
  3. Sensor Bio redirects back with an authorization code
  4. Open Wearables exchanges the code for access_token + refresh_token
  5. Tokens are stored encrypted per-user and refreshed automatically on expiry

​
Data sync

​
Workouts

Fetched from /v1/activities using cursor pagination on WorkoutStats.timestamp. Each activity includes:
  • Start/end time, duration
  • Workout type (mapped from likely_name or _workout_name)
  • Average, max, and min heart rate; calories; distance

​
Sleep

Fetched from /v1/sleep one day at a time (the API requires a single date parameter; there is no multi-day range for session-level sleep). Each day may return multiple sessions (overnight + nap). Each record includes:
  • Start/end time, total duration
  • Stage breakdown: deep, light, REM, awake minutes
  • Sleep score (mapped to efficiency_percent)
  • Biometrics during sleep: average HR, HRV, SpO2, resting HR
  • Sensor Bio does not label naps; sessions are stored with is_nap=false
  • Stage timeline: /v1/sleep/details/day is called once per day and returns the stage intervals for every sleep of that day; each session keeps the intervals that start inside its own window. A session is stored without the timeline when that call returns nothing.

​
Recovery

Fetched from /v1/scores one day at a time (single required date parameter). Provides daily recovery/activity/sleep scores and resting biometrics (resting HR, resting HRV, SpO2) stored as timeseries samples plus HealthScore rows.

​
24/7 Biometric timeseries

Fetched from /v1/biometrics using cursor pagination. Supports:

​
Daily step details

Fetched from /v1/step/details one day at a time. Provides steps and distance (km). Note: the endpoint returns the response body directly (no data wrapper).

​
Daily calories

Fetched from /v1/calorie/details one day at a time, in the same shape as step details. Resting Calories is stored as basal_energy, and Total Calories minus Resting Calories as active_energy.