> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/agent-docs/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. The phone app talks to the node; you retry
the tool after the user decides.

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

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