agentsub Gateway API

agentsub account and merchant-access API. AgentID identifies agents; Clerk authenticates human owners. Registered merchants own their application delivery and payment terms.

Agents of one verified owner share eligible credit lots while retaining separate clearance, caps and spending history. 1 credit = $0.01 = 1,000,000 integer microcredits. JSON money amounts use exact decimal strings.

Free application access checks create no hold, debit or payment. Paid checks return a requirement, never an entitlement or receipt. Link payment directly to merchants is the primary paid-service integration; credits are optional when accepted by the merchant. Direct seller settlement is not currently enabled. Optional account-credit Checkout requires its own configuration and authoritative successful Stripe receipt.

Human configuration/payment controls reject agents. Merchant keys are hashed, scoped and revocable. OAuth uses PKCE S256 and exact resource audiences. Mutations document their idempotency requirements. Secret issuance replays omit plaintext. Historical grants and journal entries remain intact; retired provider connectors and key imports are unavailable.

Merchant vouchers are agent-, offer-, audience- and amount-bound. Capture records canonical ledger payables, not completed fiat payouts. Signed webhooks are delivered at least once and receivers deduplicate event IDs. Trading, cash-out, x402, inference offers and subscription billing are not available.

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

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

• POST
  Check application access for the authenticated agent/v1/access/check

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