> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Pairing

> Read the Mac QR, register a device key, and store credentials safely.

Pairing binds **one install** of your app to **one node**. After that, the node trusts
signatures from that device’s Ed25519 key for `/papi/*`.

## QR / deep link

```
fau://pair?host=<host>&code=<6 digits>&fp=<fingerprint>
```

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

```json theme={null}
{
  "pairing_code": "482913",
  "device_name": "Pixel 8",
  "device_pubkey": "<base64url raw 32-byte Ed25519 public key>",
  "kind": "device_key"
}
```

| Field | Notes |
| - | - |
| `device_name` | Shown in the Mac dashboard device list |
| `device_pubkey` | Raw 32-byte public key, base64url (no PEM) |
| `kind` | Use `device_key` today. `passkey` is reserved / not required for compliance |

### Success `200`

```json theme={null}
{
  "node_id": "<node id>",
  "device_id": "dv_…",
  "mail_address": "user@gmail.com"
}
```

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_id`s.
* 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](https://docs.fau.run/developer/apps/signing.md). Start with
`GET /papi/pending`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.