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

# Push notifications

> Your Expo/APNs credentials; the node only stores ExponentPushToken values.

Push is a **wake signal**, not a trust boundary and not a mail channel.

## Who owns what

| Party | Owns |
| - | - |
| **Your app** | Expo/EAS project, APNs Auth Key / FCM, bundle id, `projectId` |
| **User’s node** | `devices.push_token` string; POSTs to Expo Push API on approval create |
| **Expo** | Maps each token → your project’s APNs/FCM credentials → the device |

The node **never** receives your `.p8` or FCM JSON. It never generates
`ExponentPushToken[…]`. Only the install does (via Expo SDK / native APIs).

## Register

After pair + notification permission:

1. Obtain an Expo push token for **your** EAS `projectId`.
2. `POST /papi/push-token` with `{"token":"ExponentPushToken[…]"}` (device-signed).
3. Re-register on cold start, when returning to foreground, and when the OS rotates the
   token.
4. Clear with `{"token":""}` on logout / remove-device (best effort).

## Payload contract

When an approval is created, the node sends Expo a message whose `data` is only:

```json theme={null}
{
  "approval_id": "ap_…",
  "agent_domain": "assistant.example",
  "match_code": "47",
  "kind": "access"
}
```

Lock-screen title/body may repeat domain + match code. **Never** mail subject, body,
question text, or draft content in push.

Special case: dashboard **Send test alert** uses `kind: "test"` and
`approval_id: "ap_test_push"`. Show “push works”; do **not** open a fake approval.

## On receive / tap

```
push arrives
  → if kind === test: ignore for navigation
  → else: signed GET /papi/pending (or refresh)
  → open approval_id from the fresh list
  → user decides over signed POST /papi/decide
```

If you act on the push body alone, a compromised or spoofed push channel can phish the
user. Fetch wins.

## Multi-app on one node

A node fans out to **every** paired device with a non-empty token. Your app and another
vendor’s app can both be paired; each has its own `device_id` and Expo token. Expo
routes each token to the correct APNs credentials automatically.

There is no per-app filter on the node today: every registered phone gets every approval
wake. Design for that (or only pair one approval app per household).

## Credentials setup (Expo)

```bash theme={null}
# in your app repo
eas credentials -p ios
# Push Notifications → use/upload APNs Auth Key (.p8)
eas build --platform ios --profile preview   # physical device
```

APNs keys live on **Expo’s servers** for your project. Rebuild after registering a new
test device for ad hoc.

## Fallback

Always poll. Push delay, denied permission, or Expo downtime must not strand approvals.

## Dead tokens

Nodes clear tokens when Expo reports `DeviceNotRegistered` (and similar) on tickets or
receipts. Your app should simply register a fresh token after reinstall.


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