The Google Health API is a new API built from the ground up allowing developers to query Fitbit user data. This is not just an update, it's a strategic move to ensure your apps are secure, reliable, and ready for future advancements in health technology. The API supports a new console for registering your apps, Google OAuth 2.0 support, new data types, new endpoint schema, and new response format.
The guide is designed to help developers migrate their existing Fitbit Web API apps to the new Google Health API.
Why should you migrate?
The benefits of using the Google Health API are:
- Enhanced Security: Compliance with Google's security best practices, aligning with Google's security, privacy, and identity standards.
- Consistency: Eliminates legacy inconsistencies in data formats, time zones, measurement units, and error handling for a more intuitive developer experience.
- Scalability & Future-Proofing: Designed to scale to meet future demands and supports modern protocols like gRPC.
Migrate your Users
Migrating from the Fitbit Web API to the Google Health API is more than a technical update. Your users must re-consent to your new integration due to changing the OAuth library. It is not possible for access tokens and refresh tokens to be transferred to the Google Health API and work. To assist with user retention during your migration, here are some technical and strategic suggestions for a successful migration.
The Dual-Library Strategy
Because Fitbit Web API and the Google Health API use different OAuth2 libraries, you must manage a "bridging" period where both libraries exist in your codebase.
Parallel Authorization Management
- Encapsulate Clients: Create an abstraction layer or interface for your "Health Service." This allows the rest of your app to request data without knowing which library (Fitbit OAuth versus Google OAuth) is active for that specific user.
- Database Schema Update: Update your user table to include a
oauth_typeflag. For example, usefitbitfor Fitbit OAuth andgooglefor Google OAuth.- New Users: Default to Google Health API and the Google OAuth
library. Set
oauth_typetogoogle. - Existing Users: Keep on Fitbit Web API until they complete
the re-consent flow. Set
oauth_typetofitbit.
- New Users: Default to Google Health API and the Google OAuth
library. Set
The "Step-Up" Re-consent Flow
Instead of forcing a logout, use an incremental authorization approach:
- Detect Fitbit Open Source Token: When a Fitbit Web API user opens the app, trigger a "Service Update" notification.
- Launch Google OAuth Flow: When the user clicks "Update," initiate the Google OAuth2 library flow.
- Replace & Revoke: Once the Google OAuth token is successfully
received, save it to the user profile, update the
oauth_typefromfitbittogoogle, and (if possible) programmatically revoke the oldfitbittoken to keep the user's security profile clean.
Maximize User Retention
Re-consent is the "danger zone" for churn. To prevent users from abandoning the app, follow these UX best practices:
The "Value-First" Communication
Don't lead with "We updated our API." Lead with the benefits of the new Google-backed system:
- Enhanced Security: Mention Google's industry-leading account protection and 2FA.
- Reliability: Faster sync times and more stable data connections.
- Feature Gating: Gently inform users that new features and data types require the update.
Smart Timing
- Don't Interrupt High-Value Tasks: Never trigger the re-consent screen while a user is in the middle of a workout or logging food.
- The "Nudge" Phase: For the first 30 days, use a dismissible banner.
- The "Hard Cutoff" Phase: Only make the re-consent mandatory after several weeks of warnings, coinciding with the official Fitbit Web API deprecation deadlines.
Migration Flow Comparison
A clear visual distinction between the old and new flows helps developers understand where the logic forks.
| Feature | Fitbit Web API (Legacy) | Google Health API (Google-Identity) |
| Auth Library | Standard Open Source | Google Identity Services (GIS) / Google Auth |
| User Accounts | Fitbit Legacy Credentials | Google Account |
| Token Type | Fitbit-specific Access / Refresh | Google-issued Access/Refresh tokens |
| Scope Management | Broad permissions | Granular / Incremental permissions |
Handle the Account Migration Nuance
According to Fitbit's documentation, users migrating their account to Google generally don't lose their 3rd-party connections immediately, but changing the API version is a developer-side requirement.
- Check Token Validity: Use a backgroundworker to check if Fitbit tokens are failing with "Unauthorized" errors. This may indicate the user has migrated their account but your app hasn't caught up.
- Graceful Failures: If a Fitbit OAuth call fails, redirect the user to a custom "Reconnect Fitbit" page that specifically uses the new Google OAuth flow.