Overview & Concepts

Mental model (in 60 seconds)

The DATEYE Connector Protocol is a privacy-first API that any backend can implement to receive biometric measurements from the DATEYE desktop client. myopia.kids is the reference implementation — the protocol itself is generic and product-neutral.

The flow works in five steps:

Onboarding: The practice generates a setup code (MK-XXXX-XXXX) in your portal. The client redeems it via POST /setup/redeem and receives an API key, the base URL (host), and an encryptionKey (used only for the DB-passphrase backup).
Auth: Every subsequent request carries Authorization: Bearer <apiKey>.
Import: The client sends measurements via POST /import. It identifies patients solely by a devicePseudonym (a stable, client-computed HMAC hash) plus coarse hints (initials, birth month/year) — no PII.
Linking: Unknown patients land in a pending queue. A human links them to a real patient record in the portal (the server cannot do this automatically — it has no PII). After linking, the server remembers the mapping devicePseudonym → clientId.
Back-channels: The client polls GET /practice/mappings (which pseudonyms are now linked or revoked) and GET /rejected-clients (which pseudonyms to stop sending).

The server never learns who the patient is — only that “pseudonym X” has measurements. The link to identity is made by a human in the portal and stays there.

Transport & conventions

Aspect	Value
Base URL (prod)	Your own domain (e.g. `https://myopia.kids` in the reference implementation)
Base URL (staging)	Your staging domain (e.g. `https://dev.myopia.kids`)
Versioning	Path prefix `/api/v1/`
Content-Type	`application/json` (request & response)
Auth	`Authorization: Bearer <apiKey>` (alternatively `X-API-Key: <apiKey>`)
Timestamps	ISO-8601 UTC (`2026-07-15T10:30:00.000Z`)
Success envelope	`{ "success": true, "data": { … } }`
Error envelope	`{ "success": false, "error": { "code": "…", "message": "…" } }`

Telemetry headers (optional, set by the client, stored by the server on the API key):

Header	Meaning	Limit
`X-Hostname`	Machine name of the installation	printable ASCII, ≤255
`X-DATEYE-Version`	Client version (semver)	≤32
`X-DATEYE-OS`	`windows` or `macos` (lowercase)	—
`X-DATEYE-Edition`	Product edition	≤32
`X-DATEYE-Canary-Consent`	`1`/`0` — opt into the canary update channel	—

Rate limits (recommended to adopt 1:1 so the client behaves identically):

Authenticated endpoints: 120 requests / 60 s per API key (sliding window). On exceed: 429 with header Retry-After: <seconds>.
POST /setup/redeem (unauthenticated): 10 attempts / hour per IP.