How to Connect Samsung Health to Your App

Open Wearables Team · May 5, 2026 · 8 min read

Introduction

Samsung Health is one of the most widely used health platforms on Android. Connecting your application to it requires working through a multi-step process that differs meaningfully from most other wearable APIs. There is a gated developer program, a non-trivial OAuth implementation, and a data schema you will need to normalize before it is useful to your product. This guide covers each step in the order you will encounter it.

The payoff is access to an ecosystem that includes Galaxy Watch biometrics across tens of millions of users: continuous heart rate, HRV, stress score, sleep staging with SpO2 and breathing irregularity detection, body composition from Galaxy Watch 5 and newer, and nightly skin temperature from Galaxy Watch 6 and newer. For developers building multi-provider health apps that need solid Android coverage, Samsung Health is typically a required integration.

Before You Write Code: Developer Program

Samsung Health Platform is not a self-serve API. Before you can obtain client credentials, you must apply to the Samsung Health Developer Program through the Samsung developer portal. The application form asks for your company name, app description, intended data usage, user population, data storage and security practices, and which data types you need access to.

Be specific and honest in the application. Vague descriptions of intended use or overly broad data type requests tend to slow approval or result in follow-up questions from Samsung's review team. If your use case is consumer wellness or fitness coaching, say so. If you need body composition and stress data specifically, list those data categories and explain why.

Approval takes five to fifteen business days in most cases. Some applications in less common categories or with clinical data handling requirements take longer. Apply at the start of your integration planning, not when you are ready to test. If you are building with Open Wearables, the project's existing Samsung Health credentials can cover development access while you wait for your own production approval.

Once approved, Samsung provides a client_id and client_secret for each environment. Keep your production credentials separate from development credentials. Treat them as secrets and do not expose them in client-side code.

OAuth and Token Management

Samsung Health uses OAuth 2.0 with the authorization code flow. Your app redirects users to Samsung's authorization server where they log in with their Samsung account and grant permissions. Samsung returns an authorization code which you exchange for access and refresh tokens at Samsung's token endpoint.

The scopes you request determine which data types your access token can fetch. The main scopes are r:exercise for workout sessions, r:sleep for sleep records, r:health for daily metrics including heart rate, HRV, stress score and SpO2, r:body for body composition measurements, and r:profile for user profile information.

Request only the scopes your application actually uses. Users see the scope list during authorization and excessive scope requests increase drop-off at the consent screen.

Access tokens expire after a fixed period. Use the refresh token to obtain a new access token without requiring the user to re-authorize. Store refresh tokens securely in your backend, associated with the user's account. Handle 401 Unauthorized responses from the API by first attempting a token refresh. If the refresh also fails, the user needs to re-authenticate: surface a reconnect prompt in your UI rather than silently losing their data connection.

Samsung refresh tokens do not rotate on use, which simplifies token management compared to providers like Garmin that issue a new refresh token with each exchange. Store the refresh token once and reuse it until it expires or is revoked by the user.

Working With Samsung's Data Model

Samsung Health API endpoints are organized by data type. Exercise sessions, sleep records, daily health summaries and body composition measurements each have their own endpoint and response schema. You query each endpoint with a date range and receive paginated results.

Exercise sessions include a sport_type field that uses Samsung's internal numeric sport type codes. Map these to human-readable activity names using the sport type reference table in Samsung's developer documentation. Common mappings: 1001 for running, 1002 for walking, 11007 for cycling, 2009 for swimming. For unrecognized sport types, fall back to a generic activity label rather than dropping the session.

Heart rate data within exercise sessions comes as a time series of readings at one-minute intervals. For summary statistics, Samsung provides mean and max. For aggregated daily resting heart rate, query the health endpoint for the relevant date range.

Sleep data is organized into a parent record with overall summary statistics and child records for each sleep stage interval. The stage values are: 1 for awake, 2 for light, 3 for deep and 4 for REM. Total duration is in minutes. Parse child records to build a sleep stage timeline if your product surfaces granular sleep architecture.

Stress score appears as a time series within the daily health response. Each data point has a timestamp and a score from 0 to 100. To show a daily stress summary, compute the mean across the day's readings or identify peak stress windows.

Galaxy Watch-Specific Features in Product Context

Samsung's continuous stress score is the most productively distinctive metric in the Samsung Health data model. Unlike recovery scores that are computed once per morning, stress score updates throughout the day as HRV is measured during non-exercise periods. This enables product features that are simply not possible with providers that only measure overnight.

Practical uses for intraday stress data include: identifying time-of-day stress patterns over weeks (for example, stress consistently peaks between 2pm and 4pm on workdays), correlating high-stress days with poor sleep scores the following night, and triggering wellness check-ins or breathing exercise recommendations when stress readings spike.

Body composition from Galaxy Watch 5 and newer is measured via BIA. The measurement requires the user to hold specific contact points on the watch. Results include body fat percentage, skeletal muscle mass, body water percentage and BMI. These measurements are point-in-time rather than continuous, so users will have one or a few readings per day rather than a time series. Treat them as periodic assessments and track trend over weeks.

Skin temperature from Galaxy Watch 6 and newer is a nightly measurement recorded during sleep. Samsung reports it as a deviation from the user's established baseline rather than an absolute temperature. A positive deviation may indicate elevated recovery burden, illness or hormonal cycle phase. Surface it similarly to how Oura presents temperature deviation: as a trend signal rather than a standalone daily alarm.

Handling Device Heterogeneity

Not all Samsung Health users have a Galaxy Watch. The Samsung Health app also runs on Android phones and aggregates data from manual entries and third-party apps. When a user connects Samsung Health, you will not always know their hardware.

Design your data pipeline to handle missing fields gracefully. A user without a Galaxy Watch will have no HRV, no stress score and no SpO2. A user with a Galaxy Watch 4 or older will have no body composition and no skin temperature. Nullable fields in your schema and conditional logic in your product UI are both required.

You can infer approximate hardware from which metrics appear in the data, but this is fragile as a long-term approach since users change devices and data availability changes with firmware updates. It is better to surface available metrics dynamically based on what the API returns for each user rather than hardcoding feature sets by inferred device model.

Open Wearables

Open Wearables is an open source project that handles Samsung Health OAuth, token lifecycle management and data normalization. It maps Samsung's data schema to a unified model shared across supported providers including Garmin, Whoop, Polar, Suunto, Ultrahuman, Oura, Google Health Connect and Apple HealthKit.

For teams building multi-provider health applications, Open Wearables eliminates the need to implement and maintain separate data pipelines for each wearable ecosystem. Your backend receives normalized health data regardless of whether the user has a Galaxy Watch, a Garmin Fenix or a Whoop band. Self-hosted, MIT licensed, no per-user fees.

FAQ

Do I need a separate developer application for each Samsung Health data type?

No. Your developer program application covers your entire integration. You specify which data types you need in the application, and your approved credentials grant access to those scopes. If you later need additional data types, you may need to submit an amendment to your application.

Can I poll Samsung Health continuously or is there a rate limit?

Samsung Health Platform has rate limits per application and per user. Polling more frequently than once per hour per user for most data types is unnecessary and risks hitting rate limits. Implement daily or near-daily syncs for historical data and use webhooks or scheduled jobs rather than high-frequency polling.

How far back does Samsung Health data go?

Samsung Health typically provides access to data from the past year within the API. Historical data availability depends on how long the user has been using Samsung Health and whether they have synced their device consistently. Very old data may not be available via the API even if the user has it on their device.

What happens when a user revokes Samsung Health permissions?

When a user revokes authorization, your access and refresh tokens become invalid. API calls will return 401 errors. Handle this by detecting persistent 401 responses after a failed token refresh and surfacing a reconnect prompt. Do not delete the user's already-synced historical data unless they explicitly request it.

Is there a sandbox environment for testing Samsung Health integrations?

Samsung provides a development environment with separate credentials. You can use this environment to test OAuth flows and API responses. However, you will need a real Galaxy Watch and Samsung Health account with actual data to fully test data parsing, since Samsung does not provide a mock data generator for all metrics.