Human handoff

When a site asks for a human check, give your person a link or QR code, poll for the result, and continue with the pass.

Agents cannot, and should not, pass the press-and-hold check. When a site challenges an agent session, the response includes a handoff: a link the agent's person opens on their own device to complete the check, after which the agent can continue.

When you get one

Challenges go to an agent session when the request comes from a signed agent, matches an agent policy label, has an AI or headless User-Agent, or shows an agent or automation finding.

• A browser session gets 428 with "status": "challenge_required".
• A signed agent on the agent API gets 403.

{
  "status": "challenge_required",
  "handoff": {
    "id": "hof_…",
    "url": "https://shop.example/handoff/hof_…",
    "poll": "https://shop.example/v1/handoff/hof_…",
    "qrSvg": "<svg …>",
    "expiresAt": "2026-09-25T10:05:00Z",
    "interval": 2
  }
}

The handoff URL is also in the AgentGate-Handoff and Link response headers.

1. Show your person the link

Display url, or render qrSvg so they can scan it with their phone. Tell them what you were trying to do. The page asks them to press and hold (or to wait, if they cannot hold) and never asks for passwords or payment.

2. Poll

Call GET poll every interval seconds, or long-poll with ?wait=8. Poll from the same session:

• a browser session sends the ag_session cookie it already has;
• on the agent API, sign the GET over @authority, @method and @path.

Anyone else gets 404.

3. Collect the pass

When the reply is {"status": "passed", "pass": "…", "passKind": "hold"}:

• browser session: the response also sets the ag_pass cookie; resubmit with your cookie jar;
• agent API: send AgentGate-Pass: <pass> on your next signed requests (valid for 15 minutes).

Properties