Withings API Integration

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

Overview

Withings provides access to body composition, blood pressure, activity, sleep, and workout data from Withings scales, blood pressure monitors, and watches through the Withings Public API. The integration uses OAuth 2.0 for authentication and supports both pull-based REST syncing and push notifications. Withings deviates from every other provider here in one important way: notification subscriptions are created per user, with that user’s own access token, rather than once for the whole application. There is no application-level webhook registration step to run before users connect.

Supported data types

Everything Open Wearables currently imports from Withings, with the Withings API plan each item needs:

Data Type	What is imported	Free plan
Body composition	Weight, height, body fat % and mass, lean body mass, skeletal muscle mass, body water mass, bone mass	Yes
Blood pressure & heart rate	Systolic, diastolic, spot heart rate	Yes
Blood oxygen (SpO2)	Spot measurements	Partial - manual readings only; automatic SpO2 from watches needs a paid plan
Body temperature	Thermo readings	Yes
Skin temperature	Spot measurements	No - paid plans only
Blood glucose	Spot measurements	Unknown - not on Withings’ biomarker pack list
Pulse wave velocity	Spot measurements	No - paid plans only
VO2 max, cardiovascular age	Spot measurements	No - paid plans only
Metabolic age	Spot measurements	Unknown - not on Withings’ biomarker pack list
Daily activity	Steps, distance, active calories, passive calories (derived as total minus active)	Yes
Sleep	Nightly summary: total duration, time in bed, efficiency, deep/light/REM/awake totals, nap flag	Yes
Workouts	Type, duration, average/min/max heart rate, steps, calories, distance	Yes

The Free plan column reflects Withings’ Basic Biomarker Pack. Metrics in the Total Biomarker Pack are not available on the free plan and require an Enterprise, Healthcare or Research plan (some as paid add-ons). See Available Health Data for the per-metric and per-device breakdown. Not imported today: sleep stage timeline (hypnogram), sleep score, HRV, ECG, segmental body composition, visceral fat, nerve health scores.

Data delivery

Method	Description
Polling (pull) - default	Open Wearables fetches body measures, daily activity, sleep, and workouts via the Withings Measure and Sleep APIs. This is the default live-sync mode and needs no extra setup beyond OAuth.
Webhooks (push) - opt-in	Withings notifies Open Wearables when new data is available for a user. Subscriptions are per-user (see below), so enabling webhooks requires a publicly reachable callback before any subscription can be created.

Withings defaults to pull rather than webhooks, unlike Oura. Enabling webhooks (Enable webhooks (optional) below) requires a publicly reachable HTTPS callback URL up front - there’s no way to defer that requirement the way polling lets you.

What you need by the end

App credentials: Client ID + Client Secret from a Withings Public API integration application
Redirect URI registered with your Withings application
Webhook token set (only if enabling webhooks) - a secret value Withings echoes back on your callback URL

Prerequisites

A Withings account - the same one used by device owners. Withings recommends creating a dedicated account for your organization if you’re integrating on behalf of others, but a personal account works too.
No partner approval process: Withings Public API access is free and self-serve.
The free plan is capped at 1,000 active users per application and exposes only the basic biomarkers (activity, sleep, body, heart). Larger deployments need an Enterprise, Healthcare or Research plan, which lift the user cap and raise the rate limit - see Withings API plans and the Rate Limits section below.

Application walkthrough

Create a Withings application

Sign in to the Withings Developer Dashboard with your Withings account and select Create an application. Under application type, choose Public API integration, accept the terms, and continue.Fill in the application form:

Application Name: The name shown to users on the consent screen (e.g. “Open Wearables”)
Description: A short description of your application
Registered URLs (Callback URI): Your OAuth callback URL. Open Wearables derives this from your API_BASE_URL as {API_BASE_URL}/api/v1/oauth/withings/callback, so register that exact URL here. Withings rejects localhost and bare IP addresses in this field too - for local development, expose your backend with ngrok and register e.g. https://your-subdomain.ngrok-free.app/api/v1/oauth/withings/callback. In production use your public domain.

Save the application to reveal your Client ID and Client Secret.

Keep your Client Secret server-side only - never log or expose it in client code.

Configure credentials in Open Wearables

Add the following to your .env file:

# Public base URL of your API. The OAuth redirect URI is derived from this as
# {API_BASE_URL}/api/v1/oauth/withings/callback. For local dev, use your ngrok URL.
API_BASE_URL=https://your-subdomain.ngrok-free.app

#--- Withings ---#
WITHINGS_CLIENT_ID=your-withings-client-id
WITHINGS_CLIENT_SECRET=your-withings-client-secret
WITHINGS_DEFAULT_SCOPE=user.info,user.metrics,user.activity
# Required only if enabling webhooks. Generate with: openssl rand -hex 32
WITHINGS_WEBHOOK_TOKEN=replace-with-a-random-secret

Configuration details:

Variable	Description
`API_BASE_URL`	Public base URL of your API. The OAuth redirect URI is derived from it as `{API_BASE_URL}/api/v1/oauth/withings/callback`, which must match the Callback URI registered in your Withings application. For local dev, use your ngrok URL
`WITHINGS_CLIENT_ID`	Client ID from the Withings Developer Dashboard
`WITHINGS_CLIENT_SECRET`	Client Secret from the Withings Developer Dashboard
`WITHINGS_DEFAULT_SCOPE`	OAuth scopes requested during authorization. See the OAuth Scopes Reference below
`WITHINGS_WEBHOOK_TOKEN`	Shared secret appended to your webhook callback URL as a `token` query parameter. Required only if you plan to enable webhooks - see that step below

Withings scopes are comma-separated, not space-separated. WITHINGS_DEFAULT_SCOPE=user.info,user.metrics,user.activity is correct; a space-separated value (the convention Oura and Google use) is a different string with a different meaning to Withings and will be rejected by the authorize endpoint.

Connect a user via OAuth

With credentials configured and your Open Wearables instance running, initiate the OAuth flow.1. Get the authorization URL:

curl -X GET "http://localhost:8000/api/v1/oauth/withings/authorize?user_id={user_id}&redirect_uri=http://localhost:3000/users/{user_id}" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Response:

{
  "authorization_url": "https://account.withings.com/oauth2_user/authorize2?client_id=...&redirect_uri=...&response_type=code&scope=user.info%2Cuser.metrics%2Cuser.activity&state=...",
  "state": "abc123..."
}

2. Redirect the user to the authorization_url. They will log in to Withings and authorize your app.3. Withings redirects back to the callback URI derived from API_BASE_URL ({API_BASE_URL}/api/v1/oauth/withings/callback). Open Wearables automatically exchanges the authorization code for access and refresh tokens.4. Verify the connection:

curl -X GET "http://localhost:8000/api/v1/users/{user_id}/connections" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

You should see a connection with "provider": "withings" and "status": "active".

The redirect_uri parameter in the authorize call is where the user is sent after the flow completes (e.g., back to your app). This is separate from the server-side OAuth callback ({API_BASE_URL}/api/v1/oauth/withings/callback) that Withings sends the authorization code to.

Enable webhooks (optional)

Withings subscriptions are per user: each one is created with that user’s own bearer token, so there’s nothing to register at the application level. Instead, you switch Withings’ live-sync mode to Webhook, and Open Wearables subscribes every active Withings connection using its own token; any user who connects afterward is subscribed automatically at connect time.Switch Withings to webhook mode from the dashboard:In your Open Wearables dashboard, go to Settings → Providers, find Withings, and switch its live-sync control from Periodic pull to Webhook.Open Wearables derives the callback URL from your API_BASE_URL and WITHINGS_WEBHOOK_TOKEN as {API_BASE_URL}/api/v1/providers/withings/webhooks?token={WITHINGS_WEBHOOK_TOKEN}, and subscribes each user’s connection to it via Withings’ Notify API.

This is the single most likely thing to waste your afternoon in local development. Withings enforces hard constraints on the callback URL and refuses to create a subscription otherwise:

HTTPS only - plain HTTP is rejected
Public hostname - no localhost and no IP literals, only a resolvable domain
Port 80 or 443 only - no arbitrary ports
255 characters max

Withings also sends a HEAD request to the callback URL at subscribe time to confirm it’s reachable, before the subscription is created. That means the callback must already be publicly reachable - over HTTPS, on port 443 - before you switch Withings to webhook mode or a user connects, not just before you test it. localhost and non-standard ports are always rejected, so you cannot test Withings webhooks against a local dev server without first exposing it through a public HTTPS tunnel such as ngrok on port 443. An app that never registers a compliant callback URL is capped by Withings at 10 linked users.

Switching back to Periodic pull revokes the per-user subscriptions Open Wearables created; polling keeps working regardless of webhook state.

Sync data

An initial 90-day historical sync is triggered automatically after a successful OAuth connection. To manually sync or fetch historical data:

# Sync all data types
curl -X POST "http://localhost:8000/api/v1/providers/withings/users/{user_id}/sync?data_type=all" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

You can also sync specific data types:

# Sync only workouts
curl -X POST "http://localhost:8000/api/v1/providers/withings/users/{user_id}/sync?data_type=workouts" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

# Sync only 24/7 data (body measures, activity, sleep)
curl -X POST "http://localhost:8000/api/v1/providers/withings/users/{user_id}/sync?data_type=247" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Verify the integration

Once data has synced, fetch it via the Open Wearables API:

# Fetch workouts
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/events/workouts?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

# Fetch sleep records
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/events/sleep?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

# Fetch timeseries data (body composition, blood pressure, heart rate, activity)
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/timeseries?start_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

If data is returned, your Withings integration is working end-to-end.

API Details

Detail	Value
Auth endpoint	`https://account.withings.com/oauth2_user/authorize2`
Token endpoint	`https://wbsapi.withings.net/v2/oauth2`
Data API base	`https://wbsapi.withings.net`
Webhook callback	`POST /api/v1/providers/withings/webhooks?token={WITHINGS_WEBHOOK_TOKEN}`
Webhook subscription	Per user, via Withings’ Notify API, using that user’s own bearer token - not an application-level registration

OAuth Scopes Reference

Scope	Description
`user.info`	Account information, linked devices, and goals
`user.metrics`	Body measurements (weight, body composition, blood pressure, heart rate, etc.)
`user.activity`	Physical activity and sleep data, including Sleep v2 - Getsummary
`user.sleepevents`	Bed-sensor event notifications (bed in/out, inflate completion) - not requested by default; Open Wearables doesn’t subscribe to those notification categories

The scopes requested by Open Wearables are controlled by WITHINGS_DEFAULT_SCOPE, a comma-separated list - see the warning in the configuration step above.

Rate Limits

Limit	Free plan	Paid plans
Requests per minute (application-wide)	120	1,500+
Active users per application	1,000	Unlimited

Withings enforces the request limit once per registered application, not per user - calling an endpoint for two users counts as two requests against the same allowance. Open Wearables does not pace calls against it: in pull mode every periodic sync fetches measures, activity, sleep and workouts for every connected user in one burst, and calls that hit 429 are retried a few times and then dropped. Beyond a few dozen users this will exhaust the allowance on every tick, so switch Withings to webhook mode (see Enable webhooks (optional) above) - then Open Wearables only fetches data for users Withings has just notified about. The user cap applies to the free plan only. Paid plans (Enterprise, Healthcare, Research) remove it and raise the request limit - see Withings API plans. Separately, an app that never registers a compliant webhook callback URL is capped at 10 linked users - see the webhook step above.

Next Steps

API Reference

Explore the Open Wearables API endpoints.

Coverage Matrix

See the full data coverage comparison.

Support

Need Help?

Join our Discord and ask a question.
Check GitHub Discussions.
Check the Withings Developer Documentation.

Getting started

Architecture

Health Scores

Providers

Open Wearables Mobile App

Mobile SDK

MCP Server

Developer Portal

Developer Guides

Configuration

Deployment

Support

Overview

Supported data types

Data delivery

What you need by the end

Prerequisites

Application walkthrough

API Details

OAuth Scopes Reference

Rate Limits

Next Steps

API Reference

Coverage Matrix

Support

​Overview

​Supported data types

​Data delivery

​What you need by the end

​Prerequisites

​Application walkthrough

​API Details

​OAuth Scopes Reference

​Rate Limits

​Next Steps

API Reference

Coverage Matrix

​Support

Overview

Supported data types

Data delivery

What you need by the end

Prerequisites

Application walkthrough

API Details

OAuth Scopes Reference

Rate Limits

Next Steps

Support