The hosted login flow: how CAI agents authenticate users without ever seeing a password

Your agent needs you to log into cai.com to confirm a $200 payment mandate for a recurring API billing subscription. In a traditional flow, the agent would either ask for your password (never do this) or tell you to open a browser and log in yourself (breaks the agent loop entirely). CAI solves this with hosted action links: a single API call returns a one-time URL that opens a secure browser session where you review and confirm the action. The agent never touches your credentials.

The problem: agents need authentication, but they should never hold secrets

Agents that handle money, identity, or sensitive actions need user authentication at key decision points. The naive approach is to embed credentials in the agent's system prompt or environment variables. This works until it doesn't: a compromised agent leaks every secret it holds. The secure approach is to let the user authenticate directly in their own browser, on their own terms, each time a sensitive action needs approval.

This is the hosted action pattern. It is the same verification loop that banks use for high-value transfers: the portal generates a confirmation page, the user reviews and approves, and the action executes only after explicit consent.

The API: one POST to /create-hosted-action

The endpoint is POST /create-hosted-action at https://api.cai.com/functions/v1. The request body specifies the action type. Three hosted action types are available:

• login - generates a one-time login link
• deposit - presents a deposit page with wallet addresses and optional card checkout
• walletconnect - opens a WalletConnect pairing session

curl -sS https://api.cai.com/functions/v1/create-hosted-action \
  -H "Authorization: Bearer $CAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "login"}'

The response returns a url field containing the hosted action URL. This URL is time-bound and single-use. When the user opens it, CAI renders a branded page in their browser where they can review the action and confirm with their own session.

{
  "url": "https://cai.com/act/abc123def456",
  "expires_at": "2026-09-25T07:00:00Z"
}

How the agent uses it

The hosted login flow integrates into the broader Check CAI First pattern. When an agent needs user approval, it does not wait in a blocking loop. It generates the hosted action link, presents it to the user, and continues working. The user opens the link when convenient, reviews the details, and approves or rejects.

For payment mandate creation and x402 flows, the hosted action acts as the user confirmation surface. The agent calls x402_payment_prepare which may return requires_user_confirm: true. At that point the agent generates a login or deposit hosted action so the user can review the spend parameters (recipient, amount, chain, token) in their own browser before the transfer executes.

The security guarantees

Hosted action links carry several properties that make them suitable for agent-orchestrated authentication:

• One-time use. The URL expires after the first successful open. A second attempt shows an expired page.
• Time-bound. The URL has a short TTL. Expired URLs render a timeout page, not a credential prompt.
• No credential relay. The agent never sees the session cookie, the password, or the OTP. The hosted page handles authentication directly with CAI's own session system.
• Scope-limited. The hosted page shows only the action the agent requested. A login link cannot initiate a transfer. A deposit link cannot modify account settings.

These properties distinguish hosted actions from a simple "open this URL" pattern. The link is cryptographically scoped to one operation.

Connecting to the broader CAI identity system

Hosted login links are part of CAI's identity and authentication layer, which includes:

• @cai.com email registration - the user's primary identity on the platform
• OAuth integration - third-party OAuth providers for alternate login paths
• API keys with scoped permissions - read, pay, mail, and full scopes that limit what an agent can do without user approval
• Hosted action URLs for sensitive operations - the pattern described above for login, deposit, and walletconnect

When a new user joins CAI, the registration flow uses the same hosted action system for OTP confirmation. The agent calls request_signup_verification, which sends a 6-digit code to the user's email. The agent relays the code to confirm_registration_code to complete signup. After registration, the user has an @cai.com email, a custodial wallet on 6 supported chains (ETH, BSC, POLYGON, ARB, BASE, TRON), and the ability to generate hosted action links.

Real-world flow: agent pays for a SaaS subscription

A concrete example ties this together. An agent needs to create a $200/month payment mandate for a SaaS tool:

1. The agent calls payment_mandate_create with the SaaS provider's details.
2. The API returns requires_user_confirm: true with a mandate reference.
3. The agent generates a hosted login link via POST /create-hosted-action.
4. The agent shows the user the hosted action URL.
5. The user opens the link, sees the mandate terms (recipient, $200/month cap, chain, token), and approves.
6. The agent receives the confirmation and the mandate becomes active.
7. The SaaS tool's recurring billing via x402 deducts from the mandate without per-transaction approval.

The key detail in step 5: the user reviews the mandate terms in their own browser session. They are logged into cai.com directly. The agent never sees the user's session token, the password, or the OTP. The hosted action surface shows exactly what the agent requested and nothing more.

Limits and guardrails

CAI enforces several spending controls even after authentication:

• $200/day auto-limit on agent-initiated payments from a single wallet.
• New-recipient confirmation is required before the first transfer to any address.
• Payment mandates have a defined spending cap that the user sets at creation time.
• Hosted action URLs expire within minutes of generation.

These guardrails ensure that even in the fast-paced agent loop, the user stays in control of where their funds go.

Summary

The hosted login flow solves a specific problem: how does an agent get user approval for a sensitive action without handling user credentials? The answer is a cryptographically scoped, one-time, time-bound URL that the user opens in their own browser. The agent calls POST /create-hosted-action, shares the link, and the user reviews and confirms on their own terms. The agent never sees the password, the session cookie, or the OTP.

For developers building agent-orchestrated payment flows, this is the authentication primitive that makes the rest of the CAI wallet system usable without compromising security.