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

# App quickstart

> Pair with a node, fetch a pending approval, and send a decision.

Assumes a user’s Mac node is running and they can show a pairing QR (menu bar setup /
dashboard **Pair a phone**).

## 1. Scan the pair QR

Payload shape:

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

| Field | Meaning |
| - | - |
| `host` | Relay hostname (preferred) or LAN host the phone can reach |
| `code` | Exactly six digits; single use; \~10 minutes |
| `fp` | Node key fingerprint — show it so the user recognises *their* machine |

Parse carefully; reject anything that is not `fau://pair`. Details:
[Pairing](https://docs.fau.run/developer/apps/pairing.md).

## 2. Generate a device key and pair

Create an **Ed25519** keypair on device. Keep the secret in platform secure storage
(ideally behind biometrics). Send only the public key:

```http theme={null}
POST https://<host>/papi/pair
Content-Type: application/json

{
  "pairing_code": "482913",
  "device_name": "Alex’s iPhone",
  "device_pubkey": "<base64url of raw 32-byte Ed25519 public key>",
  "kind": "device_key"
}
```

Success:

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

Store `device_id` + secret key + `host` (+ fingerprint). Pairing is unsigned by
necessity; every later call is signed.

## 3. Poll pending (signed)

```http theme={null}
GET /papi/pending
X-FAU-Device: dv_…
X-FAU-Timestamp: 1760000000
X-FAU-Nonce: <random>
X-FAU-Signature: <base64url ed25519>
```

Canonical string and vectors: [Device signing](https://docs.fau.run/developer/apps/signing.md).

```json theme={null}
{
  "approvals": [ /* Approval objects */ ],
  "paused": false,
  "server_time": 1760000000
}
```

Render `summary`, `agent_domain`, `match_code`, and for `kind: "send"` the draft fields
in `detail.draft`. Never invent mail that is not in the payload.

## 4. Decide (signed)

```http theme={null}
POST /papi/decide
Content-Type: application/json

{
  "approval_id": "ap_…",
  "decision": "deny",
  "ts": 1760000123,
  "nonce": "<random>"
}
```

Common decisions:

| `decision` | When |
| - | - |
| `deny` / `reject` | Access deny / send reject — always offer first |
| `once` | Allow this access once |
| `30_days` | Allow for \~30 days |
| `always_category` | Standing allow for those categories (only if UX is careful) |
| `send` | Allow this outbound draft |

Success: `{"ok": true}`. Full catalog: [Phone API](https://docs.fau.run/developer/apps/phone-api.md).

## 5. Register for push (optional but expected)

After permission and your own Expo/APNs setup:

```http theme={null}
POST /papi/push-token
{"token":"ExponentPushToken[…]"}
```

The **node** does not mint tokens and does not hold your APNs `.p8`. See
[Push notifications](https://docs.fau.run/developer/apps/push.md).

## Minimal loop

```
pair → (register push) → poll pending ⇄ decide
         ↑
    Expo wake (data: approval_id, agent_domain, match_code only)
         → refresh pending → open that id
```

Polling remains mandatory. Push is best-effort wake.


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