Skip to content
ContractSpec
Start here
AI index

Health Routing Strategy

Health integrations resolve providers through deterministic transport strategy order with explicit capability gating and unofficial-route controls.

Connection config fields

{
  "defaultTransport": "official-api",
  "strategyOrder": [
    "official-api",
    "official-mcp",
    "aggregator-api",
    "aggregator-mcp",
    "unofficial"
  ],
  "allowUnofficial": false,
  "unofficialAllowList": ["health.peloton"],
  "apiBaseUrl": "https://api.provider.example",
  "mcpUrl": "https://mcp.provider.example",
  "oauthTokenUrl": "https://api.provider.example/oauth/token"
}

Secret payload fields

{
  "apiKey": "...",
  "accessToken": "...",
  "refreshToken": "...",
  "clientId": "...",
  "clientSecret": "...",
  "tokenExpiresAt": "2026-02-01T00:00:00.000Z",
  "mcpAccessToken": "...",
  "webhookSecret": "..."
}

Routing behavior

  • Unsupported strategies are skipped per provider capability matrix.

  • Missing credentials fail closed and fall through only when a later strategy is valid.

  • Unofficial routes are disabled unlessallowUnofficialis true.

  • WhenunofficialAllowListis set, only listed provider keys can route unofficially.

  • OAuth refresh usesoauthTokenUrlwith refresh/client credentials when APIs return 401.

Provider guidance

  • Use official APIs when available (Whoop, Oura, Strava, Fitbit).

  • Use aggregator routing for providers without stable official APIs (Garmin, MyFitnessPal, Eight Sleep, Peloton).

  • Keep unofficial automation opt-in and auditable for production.