DATEYE

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:

  1. 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).
  2. Auth: Every subsequent request carries Authorization: Bearer <apiKey>.
  3. 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.
  4. 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.
  5. 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.