AAP · An Open Protocol for AI Agents in Financial Services

The problem

For people

Someone asks an assistant to check a balance, pay a bill, or connect an account, and the assistant drives a browser to do it. That browser runs in a datacenter and is often modified to evade CAPTCHAs and fingerprinting.

Those modifications can make a legitimate agent look malicious and get blocked. The person did nothing wrong, and their agent cannot finish the task.

For financial institutions

The institution has to know who is acting on an account, whether the customer agreed, and what they agreed to, and it has to be able to show that later. A session from a cloud browser carries none of that, so blocking it is the only defensible choice, even when it is a customer’s own agent.

Having agents announce themselves on every request does not help, because a signature any site can read is a flag any site can block on, and identity alone says nothing about consent or permissions.

Use cases

Banking and payments
A person asks an assistant to check balances, download statements, or pay a bill. The bank admits the agent for those actions, with a per-transaction limit and payments only to existing payees.
Account linking and onboarding
A person connects a bank account to another product, or opens a new one. The site keeps a record of the disclosures the person saw and the acknowledgements they gave before the agent acted.
Lending and insurance
An agent gathers documents and completes an application on a person’s behalf. The person sees every required disclosure in their own app and acknowledges it before the agent may act, and the site keeps that record.
Commerce and subscriptions
An agent buys, books, or manages a subscription for a person, and the site can tell it apart from scripted abuse of the same checkout.

Try it yourself

Your role

Open an account with Acme Bank.

aap · step 1 of 6

aap --profile site policies create \
  --origin bank.example --scopes application:write,identity:verify --max-age-days 1 \
  --data '{
  "disclosures": {
    "bundle": "onboarding-2026-09",
    "presentation": "app",
    "documents": [
      {
        "id": "terms",
        "title": "Agent access terms",
        "url": "https://bank.example/legal/agent-access-terms",
        "format": "text/html",
        "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
        "render": "link"
      },
      {
        "id": "privacy",
        "title": "Privacy policy",
        "url": "https://bank.example/legal/privacy",
        "format": "text/html",
        "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
        "render": "link"
      }
    ],
    "acknowledgements": [
      {
        "id": "authorize",
        "text": "I authorize onboarding-assistant to use the information I provide to complete and submit an account application to Acme Bank on my behalf."
      }
    ],
    "retain": "none"
  },
  "customer_actions": [
    {
      "scope": "identity:verify",
      "mode": "complete",
      "url": "https://bank.example/agent/confirm?aap_customer_action={id}",
      "expires_in": 600
    }
  ]
}'

RESPONSE EXCERPT

{
  "object": "policy",
  "origin": "bank.example",
  "scopes": [
    "application:write",
    "identity:verify"
  ],
  "max_age_s": 86400,
  "constraints": {},
  "customer_actions": [
    {
      "scope": "identity:verify",
      "mode": "complete",
      "url": "https://bank.example/agent/confirm?aap_customer_action={id}",
      "expires_in": 600
    }
  ]
}

REFERENCE SERVER · INCOMING REQUEST

import { verifyPresentation } from "./src/lib/verify.ts";

async function admitRequest(request: Request, browserSession: { id: string }) {
  const header = request.headers.get("Foil-Agent-Grant");
  if (!header) throw new Error("Missing agent grant");

  const { session } = await verifyPresentation(store, root, {
    header,
    origin: "bank.example",
    sessionId: browserSession.id,
  });

  if (session.plane !== "agent" || session.decision.verdict !== "allow") {
    throw new Error("Agent request denied");
  }

  return session;
}

VERIFIED SESSION (EXCERPT)

{
  "id": "sess_0mfom8g0300a7e3b91f20",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Open an account with Acme Bank",
    "scopes": [
      "application:write",
      "identity:verify"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g0200a7e3b91f20"
    }
  }
}

aap --profile site sessions retrieve sess_0mfom8g0300a7e3b91f20

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300a7e3b91f20",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Open an account with Acme Bank",
    "scopes": [
      "application:write",
      "identity:verify"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g0200a7e3b91f20"
    }
  }
}

aap --profile site customer-actions list \
  --session sess_0mfom8g0300a7e3b91f20 --status pending

RESPONSE EXCERPT

{
  "data": [
    {
      "id": "ca_0mfom8g0400a7e3b91f20",
      "object": "customer_action",
      "session": "sess_0mfom8g0300a7e3b91f20",
      "status": "pending",
      "scope": "identity:verify",
      "mode": "complete",
      "context": {
        "application": "app_4c7e91b2a630",
        "product": "Personal checking",
        "checks": [
          "drivers_license_capture",
          "liveness"
        ]
      },
      "display": {
        "title": "Verify your identity",
        "message": "bank.example needs to verify your identity before this application can continue. Open the link on your phone, have your ID ready, and be prepared to take a short video."
      },
      "url": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400a7e3b91f20"
    }
  ]
}

aap --profile site test customer-actions link ca_0mfom8g0400a7e3b91f20

aap --profile site customer-actions complete ca_0mfom8g0400a7e3b91f20 \
  --data '{
  "result": {
    "outcome": "passed",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ],
    "verification_reference": "vrf_7a1d9c4e820b"
  }
}'

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g0400a7e3b91f20",
  "status": "completed",
  "scope": "identity:verify",
  "context": {
    "application": "app_4c7e91b2a630",
    "product": "Personal checking",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ]
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "outcome": "passed",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ],
    "verification_reference": "vrf_7a1d9c4e820b"
  }
}

aap --profile site sessions retrieve sess_0mfom8g0300a7e3b91f20

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300a7e3b91f20",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Open an account with Acme Bank",
    "scopes": [
      "application:write",
      "identity:verify"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g0200a7e3b91f20",
      "observed": {
        "human": true,
        "customer_actions": [
          "identity:verify"
        ]
      }
    }
  }
}

aap · step 1 of 4

DATA SENT TO YOUR OPERATOR

{
  "agent": "ag_0mfom8g0000a7e3b91f20",
  "origin": "bank.example",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Open an account with Acme Bank",
  "scopes": [
    "application:write",
    "identity:verify"
  ]
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g0200a7e3b91f20",
  "object": "authorization",
  "status": "pending_consent",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000a7e3b91f20",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Open an account with Acme Bank",
  "consent": {
    "revision": "9d8845fadda6111aa62f8c0f8ba1caf6d0a6603ea9112ad8949e708bec3f5d13",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      },
      {
        "id": "identity:verify",
        "text": "Verify your identity"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "onboarding-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize onboarding-assistant to use the information I provide to complete and submit an account application to Acme Bank on my behalf."
        }
      ],
      "retain": "none"
    }
  }
}

DATA SENT TO YOUR OPERATOR

{
  "authorization": "auth_0mfom8g0200a7e3b91f20",
  "revision": "9d8845fadda6111aa62f8c0f8ba1caf6d0a6603ea9112ad8949e708bec3f5d13",
  "acceptance": {
    "acknowledged": [
      "authorize"
    ],
    "viewed": [
      "terms",
      "privacy"
    ],
    "channel": "in_app",
    "accepted_at": "2026-09-17T10:00:00Z"
  }
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g0200a7e3b91f20",
  "object": "authorization",
  "status": "active",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000a7e3b91f20",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Open an account with Acme Bank",
  "consent": {
    "revision": "9d8845fadda6111aa62f8c0f8ba1caf6d0a6603ea9112ad8949e708bec3f5d13",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      },
      {
        "id": "identity:verify",
        "text": "Verify your identity"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "onboarding-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize onboarding-assistant to use the information I provide to complete and submit an account application to Acme Bank on my behalf."
        }
      ],
      "retain": "none"
    }
  }
}

HANDOFF RECEIVED FROM YOUR OPERATOR

{
  "id": "ca_0mfom8g0400a7e3b91f20",
  "object": "customer_action",
  "session": "sess_0mfom8g0300a7e3b91f20",
  "status": "pending",
  "scope": "identity:verify",
  "mode": "complete",
  "context": {
    "application": "app_4c7e91b2a630",
    "product": "Personal checking",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ]
  },
  "display": {
    "title": "Verify your identity",
    "message": "bank.example needs to verify your identity before this application can continue. Open the link on your phone, have your ID ready, and be prepared to take a short video."
  },
  "url": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400a7e3b91f20"
}

YOUR APPLICATION UI (EXAMPLE)

{
  "title": "Finish your identity check",
  "message": "Acme Bank needs you to capture your license and complete a liveness check. Your assistant will wait.",
  "button": {
    "label": "Continue at Acme Bank",
    "href": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400a7e3b91f20"
  },
  "task_status": "waiting_for_customer"
}

COMPLETION RECEIVED FROM YOUR OPERATOR

{
  "id": "ca_0mfom8g0400a7e3b91f20",
  "status": "completed",
  "scope": "identity:verify",
  "context": {
    "application": "app_4c7e91b2a630",
    "product": "Personal checking",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ]
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "outcome": "passed",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ],
    "verification_reference": "vrf_7a1d9c4e820b"
  }
}

YOUR APPLICATION UI (EXAMPLE)

{
  "title": "Identity check complete",
  "message": "Your assistant can continue the account application. Acme Bank will confirm whether the account is opened.",
  "task_status": "ready_to_resume"
}

aap · step 1 of 6

aap --profile operator agents create \
  --name onboarding-assistant \
  --scopes application:write,identity:verify

RESPONSE EXCERPT

{
  "id": "ag_0mfom8g0000a7e3b91f20",
  "object": "agent",
  "name": "onboarding-assistant",
  "status": "active",
  "ceiling": {
    "scopes": [
      "application:write",
      "identity:verify"
    ],
    "constraints": {}
  }
}

aap --profile operator authorizations create \
  --agent ag_0mfom8g0000a7e3b91f20 --origin bank.example \
  --subject cus_8e3a1b7c29f4 --intent 'Open an account with Acme Bank' \
  --scopes application:write,identity:verify

RESPONSE EXCERPT

{
  "id": "auth_0mfom8g0200a7e3b91f20",
  "object": "authorization",
  "status": "pending_consent",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000a7e3b91f20",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Open an account with Acme Bank",
  "consent": {
    "revision": "9d8845fadda6111aa62f8c0f8ba1caf6d0a6603ea9112ad8949e708bec3f5d13",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      },
      {
        "id": "identity:verify",
        "text": "Verify your identity"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "onboarding-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize onboarding-assistant to use the information I provide to complete and submit an account application to Acme Bank on my behalf."
        }
      ],
      "retain": "none"
    }
  }
}

aap --profile operator authorizations accept auth_0mfom8g0200a7e3b91f20 \
  --revision 9d8845fadda6111aa62f8c0f8ba1caf6d0a6603ea9112ad8949e708bec3f5d13 \
  --data '{
  "acceptance": {
    "acknowledged": [
      "authorize"
    ],
    "viewed": [
      "terms",
      "privacy"
    ],
    "channel": "in_app",
    "accepted_at": "2026-09-17T10:00:00Z"
  }
}'

RESPONSE EXCERPT

{
  "id": "auth_0mfom8g0200a7e3b91f20",
  "object": "authorization",
  "status": "active",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000a7e3b91f20",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Open an account with Acme Bank",
  "consent": {
    "revision": "9d8845fadda6111aa62f8c0f8ba1caf6d0a6603ea9112ad8949e708bec3f5d13",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      },
      {
        "id": "identity:verify",
        "text": "Verify your identity"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "onboarding-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize onboarding-assistant to use the information I provide to complete and submit an account application to Acme Bank on my behalf."
        }
      ],
      "retain": "none"
    }
  }
}

aap --profile operator test browser connect \
  --authorization auth_0mfom8g0200a7e3b91f20 --asn AS14618

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300a7e3b91f20",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Open an account with Acme Bank",
    "scopes": [
      "application:write",
      "identity:verify"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g0200a7e3b91f20"
    }
  }
}

aap --profile operator customer-actions create \
  --session sess_0mfom8g0300a7e3b91f20 \
  --scope identity:verify \
  --data '{
  "context": {
    "application": "app_4c7e91b2a630",
    "product": "Personal checking",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ]
  }
}'

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g0400a7e3b91f20",
  "object": "customer_action",
  "session": "sess_0mfom8g0300a7e3b91f20",
  "status": "pending",
  "scope": "identity:verify",
  "mode": "complete",
  "context": {
    "application": "app_4c7e91b2a630",
    "product": "Personal checking",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ]
  },
  "display": {
    "title": "Verify your identity",
    "message": "bank.example needs to verify your identity before this application can continue. Open the link on your phone, have your ID ready, and be prepared to take a short video."
  },
  "url": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400a7e3b91f20"
}

aap --profile operator customer-actions wait ca_0mfom8g0400a7e3b91f20 \
  --timeout 5m

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g0400a7e3b91f20",
  "status": "completed",
  "scope": "identity:verify",
  "context": {
    "application": "app_4c7e91b2a630",
    "product": "Personal checking",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ]
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "outcome": "passed",
    "checks": [
      "drivers_license_capture",
      "liveness"
    ],
    "verification_reference": "vrf_7a1d9c4e820b"
  }
}

Pay my $142.10 utility bill.

aap · step 1 of 7

aap --profile site policies create \
  --origin bank.example --scopes accounts:read,payments:initiate --max-age-days 1 \
  --data '{
  "disclosures": {
    "bundle": "payments-2026-09",
    "presentation": "app",
    "documents": [
      {
        "id": "terms",
        "title": "Agent access terms",
        "url": "https://bank.example/legal/agent-access-terms",
        "format": "text/html",
        "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
        "render": "link"
      },
      {
        "id": "privacy",
        "title": "Privacy policy",
        "url": "https://bank.example/legal/privacy",
        "format": "text/html",
        "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
        "render": "link"
      }
    ],
    "acknowledgements": [
      {
        "id": "authorize",
        "text": "I authorize this assistant to view my accounts and initiate payments up to $200 each to my existing payees at Acme Bank. Each payment requires my approval. I can revoke this access at any time."
      }
    ],
    "retain": "none"
  },
  "customer_actions": [
    {
      "scope": "payments:initiate",
      "mode": "approve",
      "url": "https://bank.example/agent/confirm?aap_customer_action={id}",
      "expires_in": 600
    }
  ],
  "constraints": {
    "currency": "usd",
    "max_amount": 20000,
    "payees": "existing_only"
  },
  "advanced": {
    "evidence": {
      "payments:initiate": "observed"
    }
  }
}'

RESPONSE EXCERPT

{
  "object": "policy",
  "origin": "bank.example",
  "scopes": [
    "accounts:read",
    "payments:initiate"
  ],
  "max_age_s": 86400,
  "constraints": {
    "currency": "usd",
    "max_amount": 20000,
    "payees": "existing_only"
  },
  "customer_actions": [
    {
      "scope": "payments:initiate",
      "mode": "approve",
      "url": "https://bank.example/agent/confirm?aap_customer_action={id}",
      "expires_in": 600
    }
  ]
}

REFERENCE SERVER · INCOMING REQUEST

import { verifyPresentation } from "./src/lib/verify.ts";

async function admitRequest(request: Request, browserSession: { id: string }) {
  const header = request.headers.get("Foil-Agent-Grant");
  if (!header) throw new Error("Missing agent grant");

  const { session } = await verifyPresentation(store, root, {
    header,
    origin: "bank.example",
    sessionId: browserSession.id,
  });

  if (session.plane !== "agent" || session.decision.verdict !== "allow") {
    throw new Error("Agent request denied");
  }

  return session;
}

VERIFIED SESSION (EXCERPT)

{
  "id": "sess_0mfom8g0300c42d8e061b",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Pay my $142.10 utility bill",
    "scopes": [
      "accounts:read",
      "payments:initiate"
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "authorization": {
      "id": "auth_0mfom8g0200c42d8e061b"
    }
  }
}

aap --profile site sessions retrieve sess_0mfom8g0300c42d8e061b

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300c42d8e061b",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Pay my $142.10 utility bill",
    "scopes": [
      "accounts:read",
      "payments:initiate"
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "authorization": {
      "id": "auth_0mfom8g0200c42d8e061b"
    }
  }
}

aap --profile site customer-actions list \
  --session sess_0mfom8g0300c42d8e061b --status pending

RESPONSE EXCERPT

{
  "data": [
    {
      "id": "ca_0mfom8g0400c42d8e061b",
      "object": "customer_action",
      "session": "sess_0mfom8g0300c42d8e061b",
      "status": "pending",
      "scope": "payments:initiate",
      "mode": "approve",
      "context": {
        "amount": 14210,
        "currency": "usd",
        "payee": "Pacific Power",
        "invoice": "PP-2026-0917"
      },
      "display": {
        "title": "Confirm a payment",
        "message": "bill-pay-assistant wants to pay $142.10 to Pacific Power from your bank.example account. Confirm it on bank.example from your own device."
      },
      "url": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400c42d8e061b"
    }
  ]
}

aap --profile site test customer-actions link ca_0mfom8g0400c42d8e061b

aap --profile site customer-actions complete ca_0mfom8g0400c42d8e061b \
  --data '{
  "result": {
    "confirmed": true
  }
}'

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g0400c42d8e061b",
  "status": "completed",
  "scope": "payments:initiate",
  "context": {
    "amount": 14210,
    "currency": "usd",
    "payee": "Pacific Power",
    "invoice": "PP-2026-0917"
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "confirmed": true
  }
}

aap --profile site sessions retrieve sess_0mfom8g0300c42d8e061b

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300c42d8e061b",
  "status": "active",
  "agent": {
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "approvals": [
      {
        "customer_action": "ca_0mfom8g0400c42d8e061b",
        "scope": "payments:initiate",
        "context": {
          "amount": 14210,
          "currency": "usd",
          "payee": "Pacific Power",
          "invoice": "PP-2026-0917"
        }
      }
    ]
  }
}

aap · step 1 of 4

DATA SENT TO YOUR OPERATOR

{
  "agent": "ag_0mfom8g0000c42d8e061b",
  "origin": "bank.example",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Pay my $142.10 utility bill",
  "scopes": [
    "accounts:read",
    "payments:initiate"
  ]
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g0200c42d8e061b",
  "object": "authorization",
  "status": "pending_consent",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000c42d8e061b",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Pay my $142.10 utility bill",
  "consent": {
    "revision": "c41b786e98cd30499bb2f37e10763a95d076b93576e3afaca8d5bd3c6edb073e",
    "scopes": [
      {
        "id": "accounts:read",
        "text": "See your accounts and balances"
      },
      {
        "id": "payments:initiate",
        "text": "Make payments up to $200 each to payees you already have"
      }
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "payments-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to view my accounts and initiate payments up to $200 each to my existing payees at Acme Bank. Each payment requires my approval. I can revoke this access at any time."
        }
      ],
      "retain": "none"
    }
  }
}

DATA SENT TO YOUR OPERATOR

{
  "authorization": "auth_0mfom8g0200c42d8e061b",
  "revision": "c41b786e98cd30499bb2f37e10763a95d076b93576e3afaca8d5bd3c6edb073e",
  "acceptance": {
    "acknowledged": [
      "authorize"
    ],
    "viewed": [
      "terms",
      "privacy"
    ],
    "channel": "in_app",
    "accepted_at": "2026-09-17T10:00:00Z"
  }
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g0200c42d8e061b",
  "object": "authorization",
  "status": "active",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000c42d8e061b",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Pay my $142.10 utility bill",
  "consent": {
    "revision": "c41b786e98cd30499bb2f37e10763a95d076b93576e3afaca8d5bd3c6edb073e",
    "scopes": [
      {
        "id": "accounts:read",
        "text": "See your accounts and balances"
      },
      {
        "id": "payments:initiate",
        "text": "Make payments up to $200 each to payees you already have"
      }
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "payments-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to view my accounts and initiate payments up to $200 each to my existing payees at Acme Bank. Each payment requires my approval. I can revoke this access at any time."
        }
      ],
      "retain": "none"
    }
  }
}

HANDOFF RECEIVED FROM YOUR OPERATOR

{
  "id": "ca_0mfom8g0400c42d8e061b",
  "object": "customer_action",
  "session": "sess_0mfom8g0300c42d8e061b",
  "status": "pending",
  "scope": "payments:initiate",
  "mode": "approve",
  "context": {
    "amount": 14210,
    "currency": "usd",
    "payee": "Pacific Power",
    "invoice": "PP-2026-0917"
  },
  "display": {
    "title": "Confirm a payment",
    "message": "bill-pay-assistant wants to pay $142.10 to Pacific Power from your bank.example account. Confirm it on bank.example from your own device."
  },
  "url": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400c42d8e061b"
}

YOUR APPLICATION UI (EXAMPLE)

{
  "title": "Approve your utility payment",
  "message": "Approve $142.10 to Pacific Power for invoice PP-2026-0917 on your bank’s site.",
  "button": {
    "label": "Review payment at Acme Bank",
    "href": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400c42d8e061b"
  },
  "task_status": "waiting_for_customer"
}

COMPLETION RECEIVED FROM YOUR OPERATOR

{
  "id": "ca_0mfom8g0400c42d8e061b",
  "status": "completed",
  "scope": "payments:initiate",
  "context": {
    "amount": 14210,
    "currency": "usd",
    "payee": "Pacific Power",
    "invoice": "PP-2026-0917"
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "confirmed": true
  }
}

YOUR APPLICATION UI (EXAMPLE)

{
  "title": "Payment authorized",
  "message": "Your assistant can now submit the approved $142.10 payment to Pacific Power. It is not paid until the bank confirms it.",
  "task_status": "ready_to_resume"
}

aap · step 1 of 6

aap --profile operator agents create \
  --name bill-pay-assistant \
  --scopes accounts:read,payments:initiate \
  --currency usd --max-amount 20000 --payees existing_only

RESPONSE EXCERPT

{
  "id": "ag_0mfom8g0000c42d8e061b",
  "object": "agent",
  "name": "bill-pay-assistant",
  "status": "active",
  "ceiling": {
    "scopes": [
      "accounts:read",
      "payments:initiate"
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    }
  }
}

aap --profile operator authorizations create \
  --agent ag_0mfom8g0000c42d8e061b --origin bank.example \
  --subject cus_8e3a1b7c29f4 --intent 'Pay my $142.10 utility bill' \
  --scopes accounts:read,payments:initiate

RESPONSE EXCERPT

{
  "id": "auth_0mfom8g0200c42d8e061b",
  "object": "authorization",
  "status": "pending_consent",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000c42d8e061b",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Pay my $142.10 utility bill",
  "consent": {
    "revision": "c41b786e98cd30499bb2f37e10763a95d076b93576e3afaca8d5bd3c6edb073e",
    "scopes": [
      {
        "id": "accounts:read",
        "text": "See your accounts and balances"
      },
      {
        "id": "payments:initiate",
        "text": "Make payments up to $200 each to payees you already have"
      }
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "payments-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to view my accounts and initiate payments up to $200 each to my existing payees at Acme Bank. Each payment requires my approval. I can revoke this access at any time."
        }
      ],
      "retain": "none"
    }
  }
}

aap --profile operator authorizations accept auth_0mfom8g0200c42d8e061b \
  --revision c41b786e98cd30499bb2f37e10763a95d076b93576e3afaca8d5bd3c6edb073e \
  --site-session sess_0mfom8f0000c42d8e061b \
  --data '{
  "acceptance": {
    "acknowledged": [
      "authorize"
    ],
    "viewed": [
      "terms",
      "privacy"
    ],
    "channel": "in_app",
    "accepted_at": "2026-09-17T10:00:00Z"
  }
}'

RESPONSE EXCERPT

{
  "id": "auth_0mfom8g0200c42d8e061b",
  "object": "authorization",
  "status": "active",
  "origin": "bank.example",
  "agent": "ag_0mfom8g0000c42d8e061b",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Pay my $142.10 utility bill",
  "consent": {
    "revision": "c41b786e98cd30499bb2f37e10763a95d076b93576e3afaca8d5bd3c6edb073e",
    "scopes": [
      {
        "id": "accounts:read",
        "text": "See your accounts and balances"
      },
      {
        "id": "payments:initiate",
        "text": "Make payments up to $200 each to payees you already have"
      }
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "payments-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://bank.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://bank.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to view my accounts and initiate payments up to $200 each to my existing payees at Acme Bank. Each payment requires my approval. I can revoke this access at any time."
        }
      ],
      "retain": "none"
    }
  }
}

aap --profile operator test browser connect \
  --authorization auth_0mfom8g0200c42d8e061b --asn AS14618

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300c42d8e061b",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Pay my $142.10 utility bill",
    "scopes": [
      "accounts:read",
      "payments:initiate"
    ],
    "constraints": {
      "currency": "usd",
      "max_amount": 20000,
      "payees": "existing_only"
    },
    "authorization": {
      "id": "auth_0mfom8g0200c42d8e061b"
    }
  }
}

aap --profile operator customer-actions create \
  --session sess_0mfom8g0300c42d8e061b \
  --scope payments:initiate \
  --data '{
  "context": {
    "amount": 14210,
    "currency": "usd",
    "payee": "Pacific Power",
    "invoice": "PP-2026-0917"
  }
}'

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g0400c42d8e061b",
  "object": "customer_action",
  "session": "sess_0mfom8g0300c42d8e061b",
  "status": "pending",
  "scope": "payments:initiate",
  "mode": "approve",
  "context": {
    "amount": 14210,
    "currency": "usd",
    "payee": "Pacific Power",
    "invoice": "PP-2026-0917"
  },
  "display": {
    "title": "Confirm a payment",
    "message": "bill-pay-assistant wants to pay $142.10 to Pacific Power from your bank.example account. Confirm it on bank.example from your own device."
  },
  "url": "https://bank.example/agent/confirm?aap_customer_action=ca_0mfom8g0400c42d8e061b"
}

aap --profile operator customer-actions wait ca_0mfom8g0400c42d8e061b \
  --timeout 5m

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g0400c42d8e061b",
  "status": "completed",
  "scope": "payments:initiate",
  "context": {
    "amount": 14210,
    "currency": "usd",
    "payee": "Pacific Power",
    "invoice": "PP-2026-0917"
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "confirmed": true
  }
}

Apply for a $12,000 auto loan.

aap · step 1 of 6

aap --profile site policies create \
  --origin lender.example --scopes application:write --max-age-days 1 \
  --data '{
  "disclosures": {
    "bundle": "lending-2026-09",
    "presentation": "app",
    "documents": [
      {
        "id": "terms",
        "title": "Agent access terms",
        "url": "https://lender.example/legal/agent-access-terms",
        "format": "text/html",
        "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
        "render": "link"
      },
      {
        "id": "privacy",
        "title": "Privacy policy",
        "url": "https://lender.example/legal/privacy",
        "format": "text/html",
        "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
        "render": "link"
      },
      {
        "id": "application-disclosures",
        "title": "Auto loan application disclosures",
        "url": "https://lender.example/legal/auto-loan-application",
        "format": "text/html",
        "sha256": "ed8072a9b1c653f046d92e3b785a01fc6b4e90d23f7a851cb36d04e982a71f65",
        "render": "full"
      }
    ],
    "acknowledgements": [
      {
        "id": "authorize",
        "text": "I authorize this assistant to prepare my $12,000 auto loan application and submit it only after I approve. This permission is not approval of a loan or acceptance of a loan offer. I can revoke this access at any time."
      }
    ],
    "retain": "copy_required"
  },
  "customer_actions": [
    {
      "scope": "application:write",
      "mode": "approve",
      "url": "https://lender.example/agent/confirm?aap_customer_action={id}",
      "expires_in": 600
    }
  ]
}'

RESPONSE EXCERPT

{
  "object": "policy",
  "origin": "lender.example",
  "scopes": [
    "application:write"
  ],
  "max_age_s": 86400,
  "constraints": {},
  "customer_actions": [
    {
      "scope": "application:write",
      "mode": "approve",
      "url": "https://lender.example/agent/confirm?aap_customer_action={id}",
      "expires_in": 600
    }
  ]
}

REFERENCE SERVER · INCOMING REQUEST

import { verifyPresentation } from "./src/lib/verify.ts";

async function admitRequest(request: Request, browserSession: { id: string }) {
  const header = request.headers.get("Foil-Agent-Grant");
  if (!header) throw new Error("Missing agent grant");

  const { session } = await verifyPresentation(store, root, {
    header,
    origin: "lender.example",
    sessionId: browserSession.id,
  });

  if (session.plane !== "agent" || session.decision.verdict !== "allow") {
    throw new Error("Agent request denied");
  }

  return session;
}

VERIFIED SESSION (EXCERPT)

{
  "id": "sess_0mfom8g03009f12a6d83c",
  "origin": "lender.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Apply for a $12,000 auto loan",
    "scopes": [
      "application:write"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g02009f12a6d83c"
    }
  }
}

aap --profile site sessions retrieve sess_0mfom8g03009f12a6d83c

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g03009f12a6d83c",
  "origin": "lender.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Apply for a $12,000 auto loan",
    "scopes": [
      "application:write"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g02009f12a6d83c"
    }
  }
}

aap --profile site customer-actions list \
  --session sess_0mfom8g03009f12a6d83c --status pending

RESPONSE EXCERPT

{
  "data": [
    {
      "id": "ca_0mfom8g04009f12a6d83c",
      "object": "customer_action",
      "session": "sess_0mfom8g03009f12a6d83c",
      "status": "pending",
      "scope": "application:write",
      "mode": "approve",
      "context": {
        "application": "app_8d20a6e173b9",
        "amount": 1200000,
        "currency": "usd",
        "purpose": "Used car",
        "term_months": 36
      },
      "display": {
        "title": "Finish this step on lender.example",
        "message": "loan-assistant reached a step at lender.example that you need to complete yourself: fill out and submit an application. Open lender.example from your own device to continue."
      },
      "url": "https://lender.example/agent/confirm?aap_customer_action=ca_0mfom8g04009f12a6d83c"
    }
  ]
}

aap --profile site test customer-actions link ca_0mfom8g04009f12a6d83c

aap --profile site customer-actions complete ca_0mfom8g04009f12a6d83c \
  --data '{
  "result": {
    "confirmed": true
  }
}'

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g04009f12a6d83c",
  "status": "completed",
  "scope": "application:write",
  "context": {
    "application": "app_8d20a6e173b9",
    "amount": 1200000,
    "currency": "usd",
    "purpose": "Used car",
    "term_months": 36
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "confirmed": true
  }
}

aap --profile site sessions retrieve sess_0mfom8g03009f12a6d83c

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g03009f12a6d83c",
  "status": "active",
  "agent": {
    "constraints": {},
    "approvals": [
      {
        "customer_action": "ca_0mfom8g04009f12a6d83c",
        "scope": "application:write",
        "context": {
          "application": "app_8d20a6e173b9",
          "amount": 1200000,
          "currency": "usd",
          "purpose": "Used car",
          "term_months": 36
        }
      }
    ]
  }
}

aap · step 1 of 4

DATA SENT TO YOUR OPERATOR

{
  "agent": "ag_0mfom8g00009f12a6d83c",
  "origin": "lender.example",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Apply for a $12,000 auto loan",
  "scopes": [
    "application:write"
  ]
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g02009f12a6d83c",
  "object": "authorization",
  "status": "pending_consent",
  "origin": "lender.example",
  "agent": "ag_0mfom8g00009f12a6d83c",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Apply for a $12,000 auto loan",
  "consent": {
    "revision": "2b6f0e7cd23b9abf93e58f0141a984a3e12bc87c209640fb218408c50d32fdf1",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "lending-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://lender.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://lender.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        },
        {
          "id": "application-disclosures",
          "title": "Auto loan application disclosures",
          "url": "https://lender.example/legal/auto-loan-application",
          "format": "text/html",
          "sha256": "ed8072a9b1c653f046d92e3b785a01fc6b4e90d23f7a851cb36d04e982a71f65",
          "render": "full"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to prepare my $12,000 auto loan application and submit it only after I approve. This permission is not approval of a loan or acceptance of a loan offer. I can revoke this access at any time."
        }
      ],
      "retain": "copy_required"
    }
  }
}

DATA SENT TO YOUR OPERATOR

{
  "authorization": "auth_0mfom8g02009f12a6d83c",
  "revision": "2b6f0e7cd23b9abf93e58f0141a984a3e12bc87c209640fb218408c50d32fdf1",
  "acceptance": {
    "acknowledged": [
      "authorize"
    ],
    "viewed": [
      "terms",
      "privacy",
      "application-disclosures"
    ],
    "channel": "in_app",
    "accepted_at": "2026-09-17T10:00:00Z",
    "copies_sent_to": "email"
  }
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g02009f12a6d83c",
  "object": "authorization",
  "status": "active",
  "origin": "lender.example",
  "agent": "ag_0mfom8g00009f12a6d83c",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Apply for a $12,000 auto loan",
  "consent": {
    "revision": "2b6f0e7cd23b9abf93e58f0141a984a3e12bc87c209640fb218408c50d32fdf1",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "lending-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://lender.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://lender.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        },
        {
          "id": "application-disclosures",
          "title": "Auto loan application disclosures",
          "url": "https://lender.example/legal/auto-loan-application",
          "format": "text/html",
          "sha256": "ed8072a9b1c653f046d92e3b785a01fc6b4e90d23f7a851cb36d04e982a71f65",
          "render": "full"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to prepare my $12,000 auto loan application and submit it only after I approve. This permission is not approval of a loan or acceptance of a loan offer. I can revoke this access at any time."
        }
      ],
      "retain": "copy_required"
    }
  }
}

HANDOFF RECEIVED FROM YOUR OPERATOR

{
  "id": "ca_0mfom8g04009f12a6d83c",
  "object": "customer_action",
  "session": "sess_0mfom8g03009f12a6d83c",
  "status": "pending",
  "scope": "application:write",
  "mode": "approve",
  "context": {
    "application": "app_8d20a6e173b9",
    "amount": 1200000,
    "currency": "usd",
    "purpose": "Used car",
    "term_months": 36
  },
  "display": {
    "title": "Finish this step on lender.example",
    "message": "loan-assistant reached a step at lender.example that you need to complete yourself: fill out and submit an application. Open lender.example from your own device to continue."
  },
  "url": "https://lender.example/agent/confirm?aap_customer_action=ca_0mfom8g04009f12a6d83c"
}

YOUR APPLICATION UI (EXAMPLE)

{
  "title": "Review your auto loan application",
  "message": "Review the $12,000 used-car loan application with a requested 36-month term on the lender’s site before submission.",
  "button": {
    "label": "Review application at the lender",
    "href": "https://lender.example/agent/confirm?aap_customer_action=ca_0mfom8g04009f12a6d83c"
  },
  "task_status": "waiting_for_customer"
}

COMPLETION RECEIVED FROM YOUR OPERATOR

{
  "id": "ca_0mfom8g04009f12a6d83c",
  "status": "completed",
  "scope": "application:write",
  "context": {
    "application": "app_8d20a6e173b9",
    "amount": 1200000,
    "currency": "usd",
    "purpose": "Used car",
    "term_months": 36
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "confirmed": true
  }
}

YOUR APPLICATION UI (EXAMPLE)

{
  "title": "Application submission authorized",
  "message": "Your assistant can submit the application you reviewed. The lender still decides whether to approve the loan.",
  "task_status": "ready_to_resume"
}

aap · step 1 of 6

aap --profile operator agents create \
  --name loan-assistant \
  --scopes application:write

RESPONSE EXCERPT

{
  "id": "ag_0mfom8g00009f12a6d83c",
  "object": "agent",
  "name": "loan-assistant",
  "status": "active",
  "ceiling": {
    "scopes": [
      "application:write"
    ],
    "constraints": {}
  }
}

aap --profile operator authorizations create \
  --agent ag_0mfom8g00009f12a6d83c --origin lender.example \
  --subject cus_8e3a1b7c29f4 --intent 'Apply for a $12,000 auto loan' \
  --scopes application:write

RESPONSE EXCERPT

{
  "id": "auth_0mfom8g02009f12a6d83c",
  "object": "authorization",
  "status": "pending_consent",
  "origin": "lender.example",
  "agent": "ag_0mfom8g00009f12a6d83c",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Apply for a $12,000 auto loan",
  "consent": {
    "revision": "2b6f0e7cd23b9abf93e58f0141a984a3e12bc87c209640fb218408c50d32fdf1",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "lending-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://lender.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://lender.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        },
        {
          "id": "application-disclosures",
          "title": "Auto loan application disclosures",
          "url": "https://lender.example/legal/auto-loan-application",
          "format": "text/html",
          "sha256": "ed8072a9b1c653f046d92e3b785a01fc6b4e90d23f7a851cb36d04e982a71f65",
          "render": "full"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to prepare my $12,000 auto loan application and submit it only after I approve. This permission is not approval of a loan or acceptance of a loan offer. I can revoke this access at any time."
        }
      ],
      "retain": "copy_required"
    }
  }
}

aap --profile operator authorizations accept auth_0mfom8g02009f12a6d83c \
  --revision 2b6f0e7cd23b9abf93e58f0141a984a3e12bc87c209640fb218408c50d32fdf1 \
  --data '{
  "acceptance": {
    "acknowledged": [
      "authorize"
    ],
    "viewed": [
      "terms",
      "privacy",
      "application-disclosures"
    ],
    "channel": "in_app",
    "accepted_at": "2026-09-17T10:00:00Z",
    "copies_sent_to": "email"
  }
}'

RESPONSE EXCERPT

{
  "id": "auth_0mfom8g02009f12a6d83c",
  "object": "authorization",
  "status": "active",
  "origin": "lender.example",
  "agent": "ag_0mfom8g00009f12a6d83c",
  "subject": "cus_8e3a1b7c29f4",
  "intent": "Apply for a $12,000 auto loan",
  "consent": {
    "revision": "2b6f0e7cd23b9abf93e58f0141a984a3e12bc87c209640fb218408c50d32fdf1",
    "scopes": [
      {
        "id": "application:write",
        "text": "Fill out and submit an application"
      }
    ],
    "constraints": {},
    "max_age_s": 86400,
    "disclosures": {
      "bundle": "lending-2026-09",
      "presentation": "app",
      "documents": [
        {
          "id": "terms",
          "title": "Agent access terms",
          "url": "https://lender.example/legal/agent-access-terms",
          "format": "text/html",
          "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
          "render": "link"
        },
        {
          "id": "privacy",
          "title": "Privacy policy",
          "url": "https://lender.example/legal/privacy",
          "format": "text/html",
          "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
          "render": "link"
        },
        {
          "id": "application-disclosures",
          "title": "Auto loan application disclosures",
          "url": "https://lender.example/legal/auto-loan-application",
          "format": "text/html",
          "sha256": "ed8072a9b1c653f046d92e3b785a01fc6b4e90d23f7a851cb36d04e982a71f65",
          "render": "full"
        }
      ],
      "acknowledgements": [
        {
          "id": "authorize",
          "text": "I authorize this assistant to prepare my $12,000 auto loan application and submit it only after I approve. This permission is not approval of a loan or acceptance of a loan offer. I can revoke this access at any time."
        }
      ],
      "retain": "copy_required"
    }
  }
}

aap --profile operator test browser connect \
  --authorization auth_0mfom8g02009f12a6d83c --asn AS14618

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g03009f12a6d83c",
  "origin": "lender.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Apply for a $12,000 auto loan",
    "scopes": [
      "application:write"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g02009f12a6d83c"
    }
  }
}

aap --profile operator customer-actions create \
  --session sess_0mfom8g03009f12a6d83c \
  --scope application:write \
  --data '{
  "context": {
    "application": "app_8d20a6e173b9",
    "amount": 1200000,
    "currency": "usd",
    "purpose": "Used car",
    "term_months": 36
  }
}'

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g04009f12a6d83c",
  "object": "customer_action",
  "session": "sess_0mfom8g03009f12a6d83c",
  "status": "pending",
  "scope": "application:write",
  "mode": "approve",
  "context": {
    "application": "app_8d20a6e173b9",
    "amount": 1200000,
    "currency": "usd",
    "purpose": "Used car",
    "term_months": 36
  },
  "display": {
    "title": "Finish this step on lender.example",
    "message": "loan-assistant reached a step at lender.example that you need to complete yourself: fill out and submit an application. Open lender.example from your own device to continue."
  },
  "url": "https://lender.example/agent/confirm?aap_customer_action=ca_0mfom8g04009f12a6d83c"
}

aap --profile operator customer-actions wait ca_0mfom8g04009f12a6d83c \
  --timeout 5m

RESPONSE EXCERPT

{
  "id": "ca_0mfom8g04009f12a6d83c",
  "status": "completed",
  "scope": "application:write",
  "context": {
    "application": "app_8d20a6e173b9",
    "amount": 1200000,
    "currency": "usd",
    "purpose": "Used car",
    "term_months": 36
  },
  "completed_by": {
    "human": true
  },
  "result": {
    "confirmed": true
  }
}

Stop sharing my account with this assistant.

aap · step 1 of 4

REFERENCE SERVER · INCOMING REQUEST

import { verifyPresentation } from "./src/lib/verify.ts";

async function admitRequest(request: Request, browserSession: { id: string }) {
  const header = request.headers.get("Foil-Agent-Grant");
  if (!header) throw new Error("Missing agent grant");

  const { session } = await verifyPresentation(store, root, {
    header,
    origin: "bank.example",
    sessionId: browserSession.id,
  });

  if (session.plane !== "agent" || session.decision.verdict !== "allow") {
    throw new Error("Agent request denied");
  }

  return session;
}

VERIFIED SESSION (EXCERPT)

{
  "id": "sess_0mfom8g0300b3d708e19a",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Check my account balance",
    "scopes": [
      "accounts:read"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g0200b3d708e19a"
    }
  }
}

aap --profile site sessions retrieve sess_0mfom8g0300b3d708e19a

RESPONSE EXCERPT

{
  "id": "sess_0mfom8g0300b3d708e19a",
  "origin": "bank.example",
  "status": "active",
  "plane": "agent",
  "decision": {
    "verdict": "allow",
    "plane": "agent"
  },
  "agent": {
    "intent": "Check my account balance",
    "scopes": [
      "accounts:read"
    ],
    "constraints": {},
    "authorization": {
      "id": "auth_0mfom8g0200b3d708e19a"
    }
  }
}

aap · step 1 of 2

DATA SENT TO YOUR OPERATOR

{
  "subject": "cus_8e3a1b7c29f4",
  "origin": "bank.example"
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "data": [
    {
      "id": "auth_0mfom8g0200b3d708e19a",
      "object": "authorization",
      "status": "active",
      "origin": "bank.example",
      "agent": "ag_0mfom8g0000b3d708e19a",
      "subject": "cus_8e3a1b7c29f4",
      "intent": "Check my account balance",
      "consent": {
        "revision": "70a66e8174c21bca56304ddf7e9ca426739688db584c1170cf257dae981a0b55",
        "scopes": [
          {
            "id": "accounts:read",
            "text": "See your accounts and balances"
          }
        ],
        "constraints": {},
        "max_age_s": 86400,
        "disclosures": {
          "bundle": "revoke-2026-09",
          "presentation": "app",
          "documents": [
            {
              "id": "terms",
              "title": "Agent access terms",
              "url": "https://bank.example/legal/agent-access-terms",
              "format": "text/html",
              "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
              "render": "link"
            },
            {
              "id": "privacy",
              "title": "Privacy policy",
              "url": "https://bank.example/legal/privacy",
              "format": "text/html",
              "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
              "render": "link"
            }
          ],
          "acknowledgements": [
            {
              "id": "authorize",
              "text": "I authorize this assistant to view my Acme Bank accounts and balances. It cannot make payments or change my account. I can revoke this access at any time."
            }
          ],
          "retain": "none"
        }
      }
    }
  ]
}

DATA SENT TO YOUR OPERATOR

{
  "authorization": "auth_0mfom8g0200b3d708e19a",
  "by": "consumer"
}

ILLUSTRATIVE INTEGRATION RESULT

{
  "id": "auth_0mfom8g0200b3d708e19a",
  "status": "revoked",
  "revoked_by": "consumer"
}

aap · step 1 of 3

aap --profile operator authorizations list \
  --origin bank.example --subject cus_8e3a1b7c29f4 --status active

RESPONSE EXCERPT

{
  "data": [
    {
      "id": "auth_0mfom8g0200b3d708e19a",
      "object": "authorization",
      "status": "active",
      "origin": "bank.example",
      "agent": "ag_0mfom8g0000b3d708e19a",
      "subject": "cus_8e3a1b7c29f4",
      "intent": "Check my account balance",
      "consent": {
        "revision": "70a66e8174c21bca56304ddf7e9ca426739688db584c1170cf257dae981a0b55",
        "scopes": [
          {
            "id": "accounts:read",
            "text": "See your accounts and balances"
          }
        ],
        "constraints": {},
        "max_age_s": 86400,
        "disclosures": {
          "bundle": "revoke-2026-09",
          "presentation": "app",
          "documents": [
            {
              "id": "terms",
              "title": "Agent access terms",
              "url": "https://bank.example/legal/agent-access-terms",
              "format": "text/html",
              "sha256": "6a32b87e9f1c04d5e8a763b2019dfc45a67e12b3980cd6f154ba8e2793d05c61",
              "render": "link"
            },
            {
              "id": "privacy",
              "title": "Privacy policy",
              "url": "https://bank.example/legal/privacy",
              "format": "text/html",
              "sha256": "b91f4c6a8023de75f19b04a86c2e730d9a65f81c4b0e39d275ac16f8e42b9307",
              "render": "link"
            }
          ],
          "acknowledgements": [
            {
              "id": "authorize",
              "text": "I authorize this assistant to view my Acme Bank accounts and balances. It cannot make payments or change my account. I can revoke this access at any time."
            }
          ],
          "retain": "none"
        }
      }
    }
  ]
}

What the specification covers

Agent identity
Operator and agent certificates under one root of trust, with a vetting level and third-party attestations.
Site policy
Which agents a site admits, how far they may go, and what a person must be shown before an agent acts.
Permissions
Explicit scopes for each action, with institution-defined limits on amounts, totals, counts, and payees.
Consent and disclosures
Terms served to the agent’s app, the documents and acknowledgements a person must give, and where acceptance may happen.
User and agent intent
The customer’s task is bound to their authorization and carried into the verified browser session.
Authorization
One time-limited authorization, from the permissions and disclosures shown to the customer through acceptance, browser access, and revocation.
Presentation and binding
A challenge only participating sites trigger, a header only the verifier sees, and detection that keeps running after admission.
Optional evidence
Institutions can accept W3C Verifiable Credentials from identity and risk providers or an application’s own checks. Attestations are not required by the core protocol.
Handoff, revocation, and records
Steps the person completes on the site, revocation by the site or the person, and a signed record kept for compliance.

Get involved

Stay in the loop

Leave your email and we will write when the specification changes or there is something to test.

The problem

For people

For financial institutions

Use cases

Set your access policy

Verify the agent

Confirm permissions

Review the customer action

Complete the customer check

Let the agent continue

Show the requested access

Record explicit consent

Guide the customer’s next step

Continue after confirmation

Register the agent

Request authorization

Record customer consent

Connect the browser

Request the customer check

Wait for completion

Set payment limits

Confirm the customer’s presence

Verify the agent

Confirm permissions

Review the customer action

Record customer approval

Let the agent continue

Show the requested access

Record explicit consent

Ask the customer to approve

Continue after confirmation

Register the agent

Request authorization

Record customer consent

Connect the browser

Request customer approval

Wait for completion

Set your access policy

Verify the agent

Confirm permissions

Review the customer action

Record customer approval

Let the agent continue

Show the requested access

Record explicit consent

Ask the customer to approve

Continue after confirmation

Register the agent

Request authorization

Record customer consent

Connect the browser

Request customer approval

Wait for completion

Verify the agent

Confirm permissions

Withdraw access

Confirm revocation

Show connected access

Disconnect the agent

Find the authorized access

Revoke the authorization

Confirm and stop work

What the specification covers

Get involved

Stay in the loop