What Is OAuth 2.0 (and How Health APIs Use It)?

OAuth 2.0 is the industry-standard authorization framework that lets a user grant your app limited access to their data on another service without ever handing over their password. When you integrate a cloud health provider — Fitbit, Strava, Oura, Garmin, Whoop — this is almost always how the user says "yes, my app may read my heart rate." The user consents on the provider's own screen, your app receives tokens scoped to just the data you asked for, and the user can revoke that access at any time.

This page defines the concept. For the hands-on version — registering an app, wiring the redirect, storing tokens — see the per-provider walkthroughs under /integrate. When auth breaks in production, jump to Why is my fitness API returning 401 Unauthorized?.

The authorization-code flow, in plain terms

Health APIs use OAuth's authorization-code flow. It has four moving parts, and the order matters:

1. Redirect to consent. Your app sends the user to the provider's consent screen, listing the scopes (specific permissions, e.g. read heart rate, read sleep) you are requesting.
2. User approves at the provider. The user logs in on the provider's site — not in your app — and approves. The provider redirects back to your redirect URI with a short-lived authorization code.
3. Exchange the code for tokens. Your backend swaps that code, plus your client credentials, for an access token and a refresh token.
4. Call the API, then refresh. Your app calls the API with the access token. When it expires, you use the refresh token to mint a new one — no need to re-prompt the user.

The key idea is that your app never sees the user's password. It only ever holds tokens, and those tokens are deliberately limited.

Scopes: least privilege

Scopes bind what a token can do. A token granted only the sleep scope cannot read location or write workouts. The rule of thumb is least privilege: request only the scopes your features actually use. Asking for more makes the consent screen scarier and widens the blast radius if a token leaks. Scope names differ per provider, so verify each provider's exact scope strings.

Access tokens vs. refresh tokens

These two tokens do different jobs, and confusing them is a common source of bugs:

When an access token expires you get a 401, refresh silently, and retry. When a refresh token itself stops working — revoked, rotated, or expired — the user has to re-authorize.

PKCE and state

Many health providers require two hardening additions: PKCE (Proof Key for Code Exchange), which stops an intercepted authorization code from being redeemed by an attacker, and a state parameter, which guards against cross-site request forgery on the redirect. Treat both as expected, not optional, and verify each provider's requirements.

A tiny illustrative shape of what step 3 returns:

{
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 3600,
  "scope": "sleep heartrate",
  "token_type": "Bearer"
}

You store the refresh_token securely on your server and use the access_token on the Authorization: Bearer … header of each request until it expires.

Why health APIs use OAuth

Health data is user-owned and sensitive, and OAuth's design maps cleanly onto that:

• Explicit, granular consent. The user sees exactly which data types your app is asking for and approves them by name.
• No password sharing. Credentials stay with the provider; a token leak never exposes the user's login.
• Revocable at any time. The user can withdraw access from the provider's settings, and your tokens simply stop working.
• Limited blast radius. Scopes cap what a token can touch, and short-lived access tokens shrink the window in which a stolen one is useful.

That combination — consent, revocability, least privilege, expiry — is why it became the norm for personal health data rather than shipping around API keys or passwords.

The on-device exception

Here is the part that trips people up: on-device health stores do not use OAuth at all. Apple HealthKit (iOS) and Google Health Connect (Android) use OS-level permissions instead. The user grants access per data type in a system dialog; there is no authorization code, no access or refresh token, and no server to present a token to — the data lives on the phone and your app reads it locally.

So "how does the user authorize my app?" has two answers depending on the route:

One subtlety worth knowing: HealthKit permissions are privacy-preserving and asymmetric — an app is told nothing about read denials (so you can't tell "no data" from "access denied"), and users can silently revoke individual data types. That's a very different failure mode from an OAuth 401. For the fuller comparison, see On-device vs. cloud health data and Apple HealthKit vs. Google Health Connect.

A concrete example

To show a user's sleep from Fitbit: your app sends them to Fitbit's consent screen requesting the sleep scope. They log in at Fitbit and approve. Your server exchanges the returned code for tokens, stores the refresh token, and syncs each night — refreshing the access token whenever it expires. That's OAuth end to end.

To show sleep from an Apple Watch instead: there is no OAuth anywhere. Your iOS app asks for HealthKit sleep permission in a system dialog, the user taps allow, and you read the samples straight off the device.

Same feature, two completely different authorization models — which is exactly why it helps to know which route a given provider uses before you start wiring anything up.

Where this fits

This page defines OAuth for health data. To actually implement it, the per-provider guides under /integrate walk through registering your app, handling the redirect, and storing tokens. When the flow breaks, two fixes cover the most common failures: fitness API 401 Unauthorized for expired or rejected tokens, and refresh token not working when re-authorization is the only way out. If you're weighing whether to run all this yourself, a health-data aggregator can orchestrate OAuth for many providers behind one integration.