Agent auth and delegated access

Use this guide when searching for AgentWeb agent auth, delegated payment flows, OAuth metadata, MCP authentication, and scoped checkout examples.

Discovery

1. Read /llms.txt, /openapi.json, MCP tools, and action catalog.
2. Read OAuth metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
3. Read allowed scopes at /docs/scopes.

API key example

Authorization: Bearer aw_<key>

Agents can create a key without a browser. MCP agents call agentweb_start_api_key_signup, ask the human for the emailed verification code, and then call agentweb_complete_api_key_signup. A2A agents call tasks/create with task_type=start_api_key_signup, then task_type=complete_api_key_signup. Raw HTTP clients can use POST https://mcp.agentweb.us/api/register followed by POST https://mcp.agentweb.us/api/verify.

API keys are scoped to approved Agent Maps. Do not use AgentWeb keys for raw browser control, private account access, or unrestricted Stripe actions.

Provider connection example

For cookie-backed providers such as Hermes, agents should call agentweb_auth_status or agentweb_connection_status first. If the provider is not connected, call agentweb_start_connection, send the human to the returned live_view_url, then call agentweb_poll_connection until it returns done.

Delegated payment authority example

{
  "authority_id": "auth_123",
  "principal": {
    "type": "business",
    "id": "example_co",
    "agent_provider": "claude_code"
  },
  "scope": ["price.setup", "create.checkout_session"],
  "amount_limit": { "value": 500000, "interval": "single_use" },
  "currency": "usd",
  "expires_at": "2026-05-08T00:00:00Z",
  "revocation_url": "https://example.com/agent-authority/auth_123/revoke",
  "receipt_required": true,
  "verification_required": true,
  "created_at": "2026-05-01T00:00:00Z"
}

Create checkout session

curl -X POST https://agentweb.us/api/billing/create-checkout-session \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ops@example.com",
    "plan": "agent_network",
    "partnerName": "Example Co",
    "businessDomain": "example.com",
    "agentProvider": "claude_code",
    "agentProtocol": "mcp",
    "agentSessionId": "session_123",
    "paymentAuthority": { "authority_id": "auth_123", "scope": ["create.checkout_session"] }
  }'

Rules

• Public scans require no credentials and do not execute forms or payments.
• Private execution requires an approved Agent Map and scoped credentials.
• Paid setup requires payment authority before Stripe Checkout is created.
• Checkout success does not grant runtime access until Stripe webhook verification completes.

When to use AgentWeb auth

Use AgentWeb auth when an agent needs delegated access to an approved Agent Map, scoped checkout creation, verification artifacts, or repeated authenticated workflow execution. Do not use AgentWeb auth for one-off scraping, unrestricted account access, raw Stripe operations, or browser automation that has no reusable workflow map.