---
title: "Register Apple Health"
method: POST
path: "/health-providers/apple-health/register"
tags: ["health-providers"]
deprecated: true
---

# Register Apple Health

`POST /health-providers/apple-health/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-health/register`
- Auth: HTTP bearer

> **Deprecated.**

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).

## Query parameters

- `login_only` boolean: Recover an existing Apple identity, or return 404 without creating one.

## Headers

- `x-device-timezone` string, nullable
- `x-device-hint` string, nullable
- `x-client-platform` string, nullable

## Request body

- HealthProviderAppleRegisterRequest: Request to register Apple Health.
  - `device_uuid` string, required: Opaque device identifier persisted in iCloud-synced Keychain on the mobile side. Used as the Apple Health provider_user_id.

## Response `201`

Successful Response

- HealthProviderCallbackResponse: Response after a provider connect/callback or Apple Health register. ``result`` indicates the branch that ran: - ``connected``: a new ``HealthProviderConnection`` was created. - ``already_connected``: the caller already owns this provider identity. - ``recovered``: the provider identity maps to a different imperfect user (typical after a reinstall/new device). ``custom_token`` is set so the mobile client can ``signInWithCustomToken`` and adopt the existing user's Firebase UID.
  - `provider` 'garmin' | 'whoop' | 'coros' | 'terra' | 'apple_health', required: Health data providers (OAuth connections).
  - `provider_user_id` string, required
  - `permissions` string[], required
  - `status` 'active' | 'expired' | 'revoked' | 'error', required: Status of a health provider connection.
  - `result` 'connected' | 'already_connected' | 'recovered'
  - `custom_token` string, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-13** `67858cd90634`: 1 info
  - added the new optional `query` request parameter `login_only`
- **2026-09-18** `70faa046d249`: 2 info
  - added the new optional `header` request parameter `x-client-platform`
  - added the new optional `header` request parameter `x-device-hint`

[Operation history](https://skmtc.dev/imperfect/apis/imperfect-api/changes/health-providers/apple-health/register/post.md)

---

[API](https://skmtc.dev/imperfect/apis/imperfect-api.md) - [All operations](https://skmtc.dev/imperfect/apis/imperfect-api/llms.txt) - [OpenAPI document](https://skmtc.dev/imperfect/apis/imperfect-api/revisions/5f9db30c6e6e?raw)