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

# Approvals

> Phone prompts, match codes, and how to retry.

There is **no agent poll API** for approvals. By default, the phone app talks to the
node and you retry the tool after the user decides. A live MCP request can opt into
waiting on the existing tool call instead.

## When you get `approval_required`

Tool result JSON (inside MCP content) looks like:

```json theme={null}
{
  "error": "approval_required",
  "message": "The user has been asked on their phone. Show them the match code and retry once they allow it.",
  "approval_id": "ap_…",
  "match_code": "47",
  "summary": "…",
  "expires_at": 1760000300,
  "retry_after_seconds": 5
}
```

`match_code` is two digits (`00`–`99`). Default prompt TTL is about **300 s**.

## What to show the user

1. Your **verified agent domain** (from key verification — not a marketing name).
2. The **match code**, so they can confirm the phone prompt is the same request.

Pattern is CIBA-like: you initiate; they approve on another device; no OAuth redirect.

## How to retry

| Tools | After approve |
| - | - |
| Structured (`get_upcoming_travel`, …), `ask`, compose | Retry **same arguments**, **without** `approval_id`. The node now has a grant for your domain. |
| `get_excerpt`, `send_draft` | Retry **with** `approval_id` for that prompt. Wrong/spent/expired → `not_approved`. |

Wait at least `retry_after_seconds` (often 5) before retrying. Do not spin.

## Hold a live request

Add this header to a live `/mcp` request:

```http theme={null}
X-FAU-Wait-Approval: 1
X-FAU-Wait-Approval-Timeout: 60
```

The timeout header is optional and is capped by the approval TTL and **90 seconds**.
When approved, the node completes the held tool call, including one-shot excerpt and
send approvals. A denial returns `denied`. If the hold times out, the result is the
normal `approval_required` object with `retry_after_seconds: 5`.

This is opt-in and only applies to live MCP. Without the header, the retry contract
above is unchanged. Intermediaries and client HTTP timeouts must allow the requested
hold duration.

## Limits

| Limit | Effect |
| - | - |
| \~10 prompts / agent / hour | Extra → `rate_limited` (`retry_after_seconds` often 3600) |
| 3 denials | Domain may auto-block → later calls `denied` |
| User mute / daily cap | `rate_limited` |
| User pause-all | HTTP `401` `signature_invalid` (“paused”) or tool `denied` |

## Do not

* Call `/papi/*` (phone API — not for agents).
* Expect `/mcp` to return a capability biscuit on approval.
* Hide the match code or substitute a different identity string.


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