Keep Users Connected During a Fitness API Migration

Keep users connected during a fitness API migration

You are moving an existing fitness or health integration to a new source — a new provider, a new aggregator, or a new platform store — and the one thing you cannot afford is a wall of users whose data silently stops flowing. Here is the reality up front: connections do not transfer. OAuth grants and refresh tokens are bound to your old app or aggregator, so the new path needs a fresh user authorization no matter how clean the swap looks in your backend. This is a real re-integration, not a flag flip, and the single biggest gotcha is assuming users come along automatically. They do not — you have to run old and new in parallel, get each user to re-consent, and only then decommission the old path.

This page is the cross-cutting continuity playbook. It is vendor-neutral and applies on top of any specific move (consolidating onto an aggregator, leaving one, switching aggregators, or migrating off a deprecated API — see migrate off a deprecated fitness API).

What actually changes

The recurring truth: re-consent is almost always required because refresh tokens and provider grants are not portable between your old and new plumbing. If you are shaky on why, what is OAuth for health data covers the grant model.

The migration, step by step

The sequence below keeps users connected while you move. Adapt it to your specific move, but do not skip the parallel-run or the re-consent step.

1. Stand up the new integration alongside the old one. Run both paths at once (dual-read) so nothing stops flowing while users migrate. Never hard-cut.
2. Instrument both paths. Add per-user connection status and data-freshness dashboards on the old and new source so you can see, per cohort, who is connected and whether data is actually arriving.
3. Design and ship the re-consent UX. Build a clear in-app prompt that explains why reconnection is needed and deep-links into the new connect flow, and wire identity reconciliation so the new source's user id maps back to your user. Keep it non-blocking where possible — let old-path data keep flowing until the user reconnects.
4. Communicate ahead of time. Tell users what is changing, what they must do, and when, via email and in-app, before you start moving cohorts.
5. Migrate in waves. Move users in cohorts, not a big-bang cutover, and watch reconnection rate and data continuity per cohort before expanding.
6. Back-fill within provider caps, then reconcile gaps. Pull whatever history the new source and its permissions allow, then compare against the old path to find and document gaps. Back-fill depth is provider-dependent and capped — as of 2026, verify current per-provider limits before promising any history depth.
7. Keep rollback available. Do not decommission anything until each cohort is validated; keep the ability to fall back to the old source.
8. Chase stragglers, then decommission. Send reminders to users who have not reconnected, and only retire the old path once reconnection and data continuity are confirmed across cohorts.

Gotchas and how to keep users connected

Tokens do not carry over. The most common way to lose users is to assume the migration moves their authorization. It does not — grants and refresh tokens live with the old app or aggregator, and the new path needs a fresh grant. Plan for mandatory re-consent from day one, not as a cleanup step.

Back-fill is provider-capped, not something you control. How far back you can restore history is set by each underlying provider regardless of who your integration partner is. Terra, for example, documents caps that differ sharply by provider (reported as roughly 5 years for Garmin, about 30 days for Polar, around 3 months for Coros — as of 2026, verify current caps), and large ranges are delivered asynchronously in chunks. Expect a history gap somewhere and tell users about it rather than letting them discover it.

Silent data gaps. Because the two paths can disagree, reconcile the new source against the old during the validation window and document any gap before you cut over. This is why the dashboards in step 2 matter.

Non-reconnected users. Some users will never see the prompt. Track per-user connection state (old-connected, reconnected, failed) so reminders target only the people who still need to act, and keep the old path alive for them until they reconnect.

Do not decommission early. Keep rollback until each cohort is proven. The old source is your safety net, not dead weight, until continuity is confirmed.

Honest close

Continuity work is mostly discipline, not cleverness: run both sources, get real re-consent, migrate in cohorts, and hold rollback until the numbers say the new path is solid. Do not promise yourself or your users a seamless, zero-touch migration — re-consent is almost always required, and back-fill depth is capped by each provider. Before you commit to any timeline or history-depth claim, verify the current per-provider limits and the current docs for whichever source you are moving to.