Skip to main content
Pairing binds one install of your app to one node. After that, the node trusts signatures from that device’s Ed25519 key for /papi/*.
Rules:
  • Scheme fau, host pair (path-style URI as above).
  • code is exactly six decimal digits.
  • host must be present; prefer the relay hostname from the Mac (not 127.0.0.1).
  • fp must be present; display it during pair so the user can confirm the laptop.
The Mac also shows the six-digit code for manual entry. Same POST /papi/pair either way.

POST /papi/pair

Unsigned. The pairing code is the capability (single use, ~10 minutes).

Success 200

Persist for this install:
  • host (normalized https://…)
  • device_id
  • secret key (secure storage)
  • node fingerprint
  • optional mail_address for UI only

Failure

Typical 400 when the code is wrong, expired, or already used. Show a plain-language retry (“show the square again”), not a stack trace.

Security expectations

  • Generate the key on device. Never send the secret to your backend.
  • Prefer biometric-locked secure storage when the OS supports it.
  • One physical phone can run two apps = two pairs = two device_ids.
  • Removing the device on the Mac clears trust; your app should clear local credentials when the user chooses “remove this phone,” and best-effort clear the push token first (POST /papi/push-token with {"token":""}).

After pair

All other /papi/* calls require device signing. Start with GET /papi/pending.