IMimperfect
health-providers

Register Apple Health

Changed on

Register Apple Health as the user's health data provider.

Apple Health has no OAuth flow — the mobile client calls this endpoint after the user grants HealthKit permissions. device_uuid is an opaque identifier persisted in the iCloud-synced Keychain, so it can survive reinstalls and arrive on another phone through iCloud. login_only=True returns 404 for an unknown UUID without creating a user, provider link, or phone key. Omitting it preserves new connections. Branch behavior mirrors the OAuth callback; see _link_provider_identity.

Device timezone arrives via the X-Device-Timezone header (validated by the device_timezone dependency) so the auto-created User on the anonymous-onboarding branch lands with the caller's real IANA timezone instead of the User.create default of "UTC". Mirrors the Garmin OAuth callback path landed in #689 — required so mobile can drop its preemptive POST /users priming call (#541) and let the recovery branch of _link_provider_identity fire (#711).

post/health-providers/apple/register

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/apple/register
  • Auth
    HTTP bearer

Query parameters

login_onlyboolean

Recover an existing Apple identity, or return 404 without creating one.

Headers

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

Request body

device_uuidstring required

Opaque device identifier persisted in iCloud-synced Keychain on the mobile side. Used as the Apple Health provider_user_id.

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