AgentSub Gateway API

Reviewed live AgentSub gateway contract. Blocked fixture, synthetic-agent and legacy execution routes are omitted. This document is imported directly by GET /v1/openapi.json; static structural checks do not prove deployed runtime behavior.

Money: amounts ending Uc are canonical nonnegative int64 decimal strings. 1 credit = 1,000,000 microcredits = $0.01; 1 microcredit = $0.00000001. USD prices are exact decimal strings. Payment amounts are integer cents, minimum 50 ($0.50), disclosed to the human before approval.

Authentication: verified human Clerk session JWTs permit owner controls, merchant registration, connector management and MCP. Verified AgentID tokens or broker resource tokens permit agent operations. MCP agents require the exact canonical MCP resource audience; direct Clerk human sessions are also accepted. AgentID social Clerk sessions permit only own-agent overview and service execution; never human approvals or controls. A verified human Clerk owner and server-verified AgentID owner binding are required before agent registration. Merchant asm_ keys are hashed, scoped, revocable, and restricted to their own catalog/offers/redemptions and voucher introspection.

Idempotency: payment/service/merchant/webhook mutations require a 1–200 character key matching [A-Za-z0-9._:-]. Core ledger/register/caps/freeze operations accept nonempty keys up to 255 characters. Profile operations and OAuth exchanges do not require this header. Reuse the same key with the same payload for recovery; changed payloads conflict. Secret-issuance replays return metadata without plaintext secrets.

Real Stripe/Link approval and confirmed successful settlement are required before paid credits are minted or retained operations resume; deployments may disable payments or lack Link credentials and return actionable configuration errors. x402 is unconfigured. Welcome credits are restricted to gateway GitHub/AgentMail services. Confirmed paid network credits can cover active verified registered merchant offers subject to agent caps and allowlists. Transfers, cashout and fiat payouts are disabled. Merchant capture records a payable ledger balance, not a fiat payout.

Merchant webhook events are durably queued after canonical capture/release and delivered through configured Cloudflare Queues with signed HMAC headers, bounded retries and per-attempt receipts. Delivery is at least once; receivers must deduplicate eventId. Configuration reports whether the queue is available.

OAuth defaults to a human/agent identity choice; verified human consent issues agentsub:owner tokens, upstream AgentID authorization issues agentsub:agent tokens. An explicit requested scope constrains the available identity choice. Owner OAuth tokens live ten minutes; browser logout alone does not revoke an already-issued resource token.

AgentID social-session bindings are persisted privately only after real upstream userinfo verification, keyed to the current backend Clerk external-account ID. Signed Clerk sessions recheck that account/provider on every request; cached AgentID owner identity expires after 24 hours and then requires upstream reauthentication. Canonical immutable owner-subject binding and once-owner grants remain separately enforced by ledger registration.

Clerk may retain an expired upstream AgentID access token without a refresh token even after social sign-in/reconnection. The explicit /oauth/social/connect flow renews identity through the registered direct AgentID broker and validates it against the active Clerk external account. The API does not infer verified owner claims from robot email or client metadata.

Health

• GET
  Liveness and mode report/health

Discovery

• GET
  Served OpenAPI document/v1/openapi.json
• GET
  Voucher signing JWKS (ES256)/.well-known/jwks.json
• GET
  ACS payment configuration/.well-known/acs-configuration
• GET
  Integration status report/v1/integrations

OAuth

• GET
  OAuth authorization server metadata/.well-known/oauth-authorization-server
• GET
  Protected resource metadata (API)/.well-known/oauth-protected-resource
• GET
  Protected resource metadata (MCP)/.well-known/oauth-protected-resource/mcp
• GET
  OAuth access-token signing JWKS/oauth/jwks
• POST
  Dynamic client registration (RFC 7591)/oauth/register
• GET
  Authorization endpoint (302 to AgentID)/oauth/authorize
• GET
  AgentID authorization callback/oauth/callback
• POST
  Token endpoint (authorization_code + PKCE)/oauth/token
• GET
  Read sanitized pending OAuth consent context/oauth/request
• POST
  Choose AgentID login/oauth/select
• POST
  Explicit human owner OAuth consent/oauth/owner/consent
• POST
  Renew an AgentID social identity through the registered direct broker/oauth/social/connect

Owner

• GET
  Owner dashboard overview/v1/owner/overview
• PATCH
  Update agent spending policy/v1/owner/agents/{id}/caps
• POST
  Freeze or unfreeze an agent/v1/owner/agents/{id}/freeze
• POST
  Start agent avatar upload/v1/owner/agents/{id}/avatar/upload
• POST
  Finalize agent avatar upload/v1/owner/agents/{id}/avatar/finalize
• PATCH
  Update agent display profile/v1/owner/agents/{id}/profile
• POST
  Owner-triggered service execution/v1/owner/run

Agent

• GET
  Authenticated agent identity/v1/me
• GET
  Agent credit balance/v1/balance
• GET
  Agent ledger history/v1/history
• POST
  Register the authenticated agent/v1/agents/register
• GET
  Offer catalog/v1/catalog
• GET
  Offer detail/v1/offers/{id}
• POST
  Quote an offer/v1/quotes
• POST
  Mint an ACS voucher (hold)/v1/vouchers

Services

• GET
  Available services and pricing/v1/services/catalog
• PUT
  Configure the AgentMail connector/v1/services/connectors/agentmail
• DELETE
  Remove the AgentMail connector/v1/services/connectors/agentmail
• POST
  Execute a metered service action/v1/services/execute

Payments

• GET
  Payment provider connection status/v1/payments/status
• POST
  Create a Link checkout session/v1/payments/checkout
• POST
  Start Link connect (owner only)/v1/payments/link/connect
• GET
  Link OAuth callback (GET)/v1/payments/link/callback
• POST
  Link OAuth callback (POST)/v1/payments/link/callback
• POST
  Request an agent top-up approval/v1/payments/topups
• GET
  Poll a top-up request/v1/payments/topups/{id}
• POST
  Stripe webhook receiver (inbound only)/v1/payments/stripe/webhook

Merchant Registry

• GET
  List registered merchants/v1/merchants
• POST
  Register a merchant/v1/merchants
• GET
  Merchant detail/v1/merchants/{id}
• POST
  Verify merchant domain via DNS TXT/v1/merchants/{id}/verify-domain
• POST
  Publish a merchant offer/v1/merchants/{id}/offers
• PATCH
  Update a merchant offer/v1/merchants/{id}/offers/{offerId}
• DELETE
  Delete a merchant offer/v1/merchants/{id}/offers/{offerId}
• GET
  List merchant API keys (metadata only)/v1/merchants/{id}/api-keys
• POST
  Issue a scoped merchant API key/v1/merchants/{id}/api-keys
• DELETE
  Revoke a merchant API key/v1/merchants/{id}/api-keys/{keyId}
• GET
  Active verified merchant offers/v1/merchants/catalog

Merchant Scoped

• GET
  Fetch a redemption (hold) record/v1/redemptions/{id}
• POST
  Capture a hold/v1/redemptions/{id}/capture
• POST
  Release a hold/v1/redemptions/{id}/release
• POST
  Verify an ACS voucher offline-equivalent/v1/vouchers/introspect

MCP

• POST
  Model Context Protocol HTTP endpoint/mcp
• GET
  Unsupported stateless MCP method/mcp
• DELETE
  Unsupported stateless MCP method/mcp

Merchant Webhooks

• GET
  Read webhook configuration/v1/merchants/{id}/webhook
• PUT
  Configure verified-domain webhook; secret shown once/v1/merchants/{id}/webhook
• DELETE
  Disable webhook delivery/v1/merchants/{id}/webhook
• POST
  Rotate webhook HMAC secret; secret shown once/v1/merchants/{id}/webhook/rotate
• GET
  Read webhook delivery events and actual attempt receipts/v1/merchants/{id}/webhook/events