Approvals - Federated Agent Use

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:

{
  "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

Your verified agent domain (from key verification — not a marketing name).
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.