IMimperfect
health-providers

Handle Provider Callback

Changed on

Handle OAuth callback from health provider.

The app should call this endpoint after receiving the OAuth callback with the authorization code and state parameters. user may be None during first-time onboarding when the caller holds an anonymous Firebase token — identity is resolved via _link_provider_identity.

Flow:

  1. Validate OAuth state
  2. Delegate code exchange + token storage to alice
  3. Resolve mapping via _link_provider_identity (branches on whether the provider identity is new, already-owned, a collision, or recoverable).
post/health-providers/{provider}/callback

Request

  • Base URL
    https://api.imperfect.co (the document declares no server; this is the origin it was published from)
  • URL
    https://api.imperfect.co/health-providers/{provider}/callback
  • Auth
    HTTP bearer

Path parameters

provider'garmin' | 'whoop' | 'coros' | 'terra' | 'apple_health' required

Health data providers (OAuth connections).

Query parameters

login_onlyboolean

When true, return 404 if the provider identity does not already map to a User. Used by the mobile login flow to avoid auto-creating ghost accounts.

Headers

x-device-timezonestring nullable
x-device-hintstring nullable
x-client-platformstring nullable

Request body

codestring required

Authorization code from OAuth callback

statestring required

State parameter from callback

Response

Successful Response

provider'garmin' | 'whoop' | 'coros' | 'terra' | 'apple_health' required

Health data providers (OAuth connections).

provider_user_idstring required
permissionsstring[] required
status'active' | 'expired' | 'revoked' | 'error' required

Status of a health provider connection.

result'connected' | 'already_connected' | 'recovered'
custom_tokenstring nullable

Changes

  • 70faa046d249Revision changes
    • info

      added the new optional header request parameter x-client-platform

    • info

      added the new optional header request parameter x-device-hint