# BOTCHA - Reverse CAPTCHA for AI Agents # https://botcha.ai # Contact Contact: https://botcha.ai Contact: https://github.com/dupe-com/botcha/issues # Purpose Purpose: Prove you're a bot. Humans need not apply. Purpose: Reverse CAPTCHA system that only AI agents can pass. # APP REGISTRATION REQUIRED (v0.21.0) Registration-Required: All API endpoints require a registered app with verified email Registration-Required-Note: Register for free at POST /v1/apps with your email Registration-Required-Demo: The homepage demo at botcha.ai lets agents try challenges without registering # App Registration (START HERE — required for API access) Registration-Step-1: Ask your human operator for their email address Registration-Step-2: POST /v1/apps with {"email": "human@example.com", "name": "My App"} — saves app_id + name + app_secret (secret shown ONCE) Registration-Step-3: A 6-digit verification code is emailed to your human — ask them for it Registration-Step-4: POST /v1/apps/{app_id}/verify-email with {"code": "123456", "app_secret": "sk_..."} — enables account recovery Registration-Step-5: Use your app_id on ALL API calls via ?app_id=, X-App-Id header, or JWT claim # Full Onboarding (after registration) Onboarding-Step-1: Register yourself: POST /v1/agents/register with {"name": "my-agent", "operator": "my-org"} — gives you a persistent agent identity (requires app_id) Onboarding-Step-2: Solve challenges with app: GET /v1/challenges?app_id=... then POST /v1/challenges/{id}/verify — proves you are AI (requires app_id) Onboarding-Step-3: Access protected resources: GET /agent-only with Authorization: Bearer (requires app_id) Onboarding-Step-4: Dashboard for your human: POST /v1/auth/device-code with {"app_id": "..."}, solve the speed challenge, give them the BOTCHA-XXXX code to enter at /dashboard/code (requires app_id) Onboarding-Step-5: Lost your secret? POST /v1/auth/recover with {"email": "..."} — recovery code emailed to verified address (no app_id needed) # API API: https://botcha.ai/openapi.json API-Type: REST API-Format: OpenAPI 3.1.0 # MCP Server (Model Context Protocol) MCP: https://botcha.ai/mcp MCP-Discovery: https://botcha.ai/.well-known/mcp.json MCP-Transport: Streamable HTTP (2025-03-26 spec) MCP-Protocol: JSON-RPC 2.0 MCP-Tools: list_features, get_feature, search_docs, list_endpoints, get_endpoint, get_example MCP-Note: Ask the BOTCHA MCP server any question about features, endpoints, or code examples # Documentation Docs: https://botcha.ai Docs: https://botcha.ai/docs Docs: https://botcha.ai/whitepaper Docs: https://github.com/dupe-com/botcha#readme Docs: https://www.npmjs.com/package/@dupecom/botcha Whitepaper: https://botcha.ai/whitepaper # Verification Methods Feature: Web Bot Auth (cryptographic signatures) Feature: Speed Challenge (RTT-aware timeout - fair for all networks) Feature: Standard Challenge (5s time limit) Feature: Hybrid Challenge (speed + reasoning combined) Feature: Reasoning Challenge (LLM-only questions, 30s limit) Feature: RTT-Aware Fairness (automatic network latency compensation) Feature: Token Rotation (1-hour access tokens + 1-hour refresh tokens) Feature: Audience Claims (tokens scoped to specific services) Feature: Client IP Binding (optional token-to-IP binding) Feature: Token Revocation (invalidate tokens before expiry) Feature: Server-Side Verification SDK (@dupecom/botcha-verify for TS, botcha-verify for Python) Feature: Multi-Tenant API Keys (per-app isolation, rate limiting, and token scoping) Feature: Per-App Metrics Dashboard (server-rendered at /dashboard, htmx-powered) Feature: Email-Tied App Creation (email required, 6-digit verification, account recovery) Feature: Secret Rotation (rotate app_secret with email notification) Feature: Agent-First Dashboard Auth (challenge-based login + device code handoff) Feature: Agent Registry (persistent agent identities with name, operator, version) Feature: Agent Re-identification — prove you are the same agent in a new session via OAuth refresh token (brt_), provider API key hash, or Ed25519 keypair challenge-response Feature: Agent OAuth Device Authorization Grant (RFC 8628) — human approves at /device, agent polls for brt_... refresh token valid 90 days Feature: TAP Key Recovery — rotate lost keypair using app_secret as recovery anchor Feature: Trusted Agent Protocol (TAP) — cryptographic agent auth with HTTP Message Signatures (RFC 9421) Feature: TAP Capabilities (action + resource scoping for agent sessions) Feature: TAP Trust Levels (basic, verified, enterprise) Feature: TAP Showcase Homepage (botcha.ai — one of the first services to implement Visa's Trusted Agent Protocol) Feature: TAP Full Spec v0.16.0 — Ed25519, RFC 9421 full compliance, JWKS infrastructure, Layer 2 Consumer Recognition, Layer 3 Payment Container, 402 micropayments, CDN edge verification, Visa key federation Feature: ES256 Asymmetric JWT Signing v0.19.0 — tokens signed with ES256 (ECDSA P-256), public key discovery via JWKS, HS256 still supported for backward compatibility Feature: Remote Token Validation v0.19.0 — POST /v1/token/validate for third-party token verification without shared secrets Feature: JWKS Public Key Discovery v0.19.0 — GET /.well-known/jwks exposes BOTCHA signing public keys for offline token verification # Endpoints # Challenge Endpoints (app_id required) Endpoint: GET https://botcha.ai/v1/challenges - Generate challenge (hybrid by default) — requires app_id Endpoint: POST https://botcha.ai/v1/challenges/:id/verify - Verify a challenge — requires app_id Endpoint: GET https://botcha.ai/v1/hybrid - Get hybrid challenge (speed + reasoning) — requires app_id Endpoint: POST https://botcha.ai/v1/hybrid - Verify hybrid challenge — requires app_id Endpoint: GET https://botcha.ai/v1/reasoning - Get reasoning challenge — requires app_id Endpoint: POST https://botcha.ai/v1/reasoning - Verify reasoning challenge — requires app_id # Token Endpoints (app_id required) Endpoint: GET https://botcha.ai/v1/token - Get challenge for JWT token flow — requires app_id Endpoint: POST https://botcha.ai/v1/token/verify - Verify challenge and receive JWT token — requires app_id Endpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using refresh token — requires app_id Endpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh) — requires app_id Endpoint: POST https://botcha.ai/v1/token/validate - Validate a BOTCHA token remotely (no shared secret needed) — requires app_id # App Management Endpoints (NO app_id required — these are for registration & recovery) Endpoint: POST https://botcha.ai/v1/apps - Create new app (email required, name optional) → app_id + name + app_secret — NO app_id required Endpoint: GET https://botcha.ai/v1/apps/:id - Get app info (with email + verification status) — NO app_id required Endpoint: POST https://botcha.ai/v1/apps/:id/verify-email - Verify email with 6-digit code (app_secret auth required) — NO app_id required Endpoint: POST https://botcha.ai/v1/apps/:id/resend-verification - Resend verification email (app_secret auth required) — NO app_id required Endpoint: POST https://botcha.ai/v1/apps/:id/rotate-secret - Rotate app secret (auth required) — requires app_id # Account Recovery (NO app_id required) Endpoint: POST https://botcha.ai/v1/auth/recover - Request recovery via verified email — NO app_id required # Dashboard Auth Endpoints (app_id required) Endpoint: POST https://botcha.ai/v1/auth/dashboard - Request challenge for dashboard login — requires app_id Endpoint: POST https://botcha.ai/v1/auth/dashboard/verify - Solve challenge, get session token — requires app_id Endpoint: POST https://botcha.ai/v1/auth/device-code - Request challenge for device code flow — requires app_id Endpoint: POST https://botcha.ai/v1/auth/device-code/verify - Solve challenge, get device code — requires app_id # Dashboard Endpoints Endpoint: GET https://botcha.ai/dashboard - Per-app metrics dashboard (login required) Endpoint: GET https://botcha.ai/dashboard/login - Dashboard login page Endpoint: POST https://botcha.ai/dashboard/login - Login with app_id + app_secret Endpoint: GET https://botcha.ai/dashboard/code - Enter device code (human-facing) # Code Redemption (Unified) Endpoint: GET https://botcha.ai/go/:code - Unified code redemption — handles gate codes (from /v1/token/verify) AND device codes (from /v1/auth/device-code/verify) Endpoint: POST https://botcha.ai/gate - Submit code form, redirects to /go/:code # Agent Registry Endpoints (app_id required) Endpoint: POST https://botcha.ai/v1/agents/register - Register agent identity — requires app_id Endpoint: GET https://botcha.ai/v1/agents/:id - Get agent by ID (public, no auth) — requires app_id Endpoint: GET https://botcha.ai/v1/agents - List all agents for authenticated app — requires app_id Endpoint: DELETE https://botcha.ai/v1/agents/:id - Delete agent — requires dashboard session # Agent Re-identification (PUBLIC — no auth needed, proves same agent across sessions) Endpoint: POST https://botcha.ai/v1/agents/auth - Step 1 keypair auth: { agent_id } → { challenge_id, nonce } — PUBLIC Endpoint: POST https://botcha.ai/v1/agents/auth/verify - Step 2 keypair auth: { challenge_id, agent_id, signature } → { access_token } — PUBLIC Endpoint: POST https://botcha.ai/v1/agents/auth/provider - Provider key auth: { provider, api_key, app_id } → { access_token } — PUBLIC Endpoint: POST https://botcha.ai/v1/agents/auth/refresh - OAuth refresh: { refresh_token: "brt_..." } → { access_token } — PUBLIC # Agent OAuth — Device Authorization Grant (RFC 8628) Endpoint: POST https://botcha.ai/v1/oauth/device - Start device auth: { agent_id, app_id } → { device_code, user_code, verification_url, expires_in: 600, interval: 5 } — PUBLIC Endpoint: POST https://botcha.ai/v1/oauth/token - Poll for token: { device_code, grant_type } → { access_token, refresh_token: "brt_..." } — PUBLIC Endpoint: POST https://botcha.ai/v1/oauth/approve - Human approval: { user_code, action: "approve"|"deny" } — PUBLIC Endpoint: POST https://botcha.ai/v1/oauth/revoke - Revoke refresh token: { agent_id, app_id } — PUBLIC Endpoint: GET https://botcha.ai/v1/oauth/lookup - Agent info for approval UI: ?user_code=BOTCHA-XXXX → { agent_id, name, operator } — PUBLIC Endpoint: GET https://botcha.ai/device - Human-facing OAuth approval page (requires dashboard login) # TAP (Trusted Agent Protocol) Endpoints (app_id required) Endpoint: POST https://botcha.ai/v1/agents/register/tap - Register TAP agent with public key + capabilities — requires app_id Endpoint: GET https://botcha.ai/v1/agents/:id/tap - Get TAP agent details (includes public key) — requires app_id Endpoint: GET https://botcha.ai/v1/agents/tap - List TAP-enabled agents for app — requires app_id Endpoint: POST https://botcha.ai/v1/sessions/tap - Create TAP session with intent validation — requires app_id Endpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info — requires app_id # TAP Full Spec — JWKS & Key Management (v0.16.0) (app_id required) Endpoint: GET https://botcha.ai/.well-known/jwks - JWK Set for app's TAP agents (Visa spec standard) — requires app_id Endpoint: GET https://botcha.ai/v1/keys - List keys (supports ?keyID= query for Visa compatibility) — requires app_id Endpoint: GET https://botcha.ai/v1/keys/:keyId - Get specific key by ID — requires app_id Endpoint: POST https://botcha.ai/v1/agents/:id/tap/rotate-key - Rotate agent's TAP keypair (accepts Bearer JWT or x-app-secret header for recovery) — requires app_id or app_secret # TAP Full Spec — 402 Micropayments (v0.16.0) (app_id required) Endpoint: POST https://botcha.ai/v1/invoices - Create invoice for gated content (402 flow) — requires app_id Endpoint: GET https://botcha.ai/v1/invoices/:id - Get invoice details — requires app_id Endpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IOU against invoice — requires app_id # TAP Full Spec — Consumer & Payment Verification (v0.16.0) (app_id required) Endpoint: POST https://botcha.ai/v1/verify/consumer - Verify Agentic Consumer object (Layer 2) — requires app_id Endpoint: POST https://botcha.ai/v1/verify/payment - Verify Agentic Payment Container (Layer 3) — requires app_id # Webhooks (v0.22.0) (Bearer token with app_id claim required) Endpoint: POST https://botcha.ai/v1/webhooks - Register webhook endpoint (returns signing secret once) Endpoint: GET https://botcha.ai/v1/webhooks - List webhooks for authenticated app Endpoint: GET https://botcha.ai/v1/webhooks/:id - Get webhook details Endpoint: PUT https://botcha.ai/v1/webhooks/:id - Update url/events/enabled state Endpoint: DELETE https://botcha.ai/v1/webhooks/:id - Delete webhook config + secret + delivery logs Endpoint: POST https://botcha.ai/v1/webhooks/:id/test - Send signed test event Endpoint: GET https://botcha.ai/v1/webhooks/:id/deliveries - List last 100 delivery attempts Events: agent.tap.registered, token.created, token.revoked, tap.session.created, delegation.created, delegation.revoked # TAP Delegation Chains (v0.17.0) (app_id required) Endpoint: POST https://botcha.ai/v1/delegations - Create delegation (grantor→grantee with capability subset) — requires app_id Endpoint: GET https://botcha.ai/v1/delegations/:id - Get delegation details — requires app_id Endpoint: GET https://botcha.ai/v1/delegations - List delegations for agent (?agent_id=&direction=in|out|both) — requires app_id Endpoint: POST https://botcha.ai/v1/delegations/:id/revoke - Revoke delegation (cascades to sub-delegations) — requires app_id Endpoint: POST https://botcha.ai/v1/verify/delegation - Verify entire delegation chain — requires app_id # TAP Capability Attestation (v0.17.0) (app_id required) Endpoint: POST https://botcha.ai/v1/attestations - Issue capability attestation token (can/cannot rules with action:resource patterns) — requires app_id Endpoint: GET https://botcha.ai/v1/attestations/:id - Get attestation details — requires app_id Endpoint: GET https://botcha.ai/v1/attestations - List attestations for agent (?agent_id=) — requires app_id Endpoint: POST https://botcha.ai/v1/attestations/:id/revoke - Revoke attestation (token rejected on future verification) — requires app_id Endpoint: POST https://botcha.ai/v1/verify/attestation - Verify attestation token + optionally check specific capability — requires app_id # Agent Reputation Scoring (v0.18.0) (app_id required) Endpoint: GET https://botcha.ai/v1/reputation/:agent_id - Get agent reputation score (0-1000, 5 tiers) — requires app_id Endpoint: POST https://botcha.ai/v1/reputation/events - Record a reputation event (18 action types, 6 categories) — requires app_id Endpoint: GET https://botcha.ai/v1/reputation/:agent_id/events - List reputation events (?category=&limit=) — requires app_id Endpoint: POST https://botcha.ai/v1/reputation/:agent_id/reset - Reset reputation to default (admin action) — requires app_id # Legacy Endpoints Endpoint: GET https://botcha.ai/api/challenge - Generate standard challenge Endpoint: POST https://botcha.ai/api/challenge - Verify standard challenge Endpoint: GET https://botcha.ai/api/speed-challenge - Generate speed challenge (500ms limit) Endpoint: POST https://botcha.ai/api/speed-challenge - Verify speed challenge # x402 Payment Gating (Epic 3 — agents pay USDC, skip the challenge) # Payment IS the credential on these endpoints — no app_id required Feature: x402 HTTP Payment Required protocol — verified agents pay $0.001 USDC on Base and receive a BOTCHA token Feature: Pay-for-verification — agents that don't want to solve a challenge can pay instead Feature: Double-gated resources — requires BOTH BOTCHA token AND x402 micropayment Feature: Webhook settlement — x402 facilitators notify BOTCHA of on-chain payments Feature: Cryptographic EIP-712 signature verification (ERC-3009 transferWithAuthorization) Endpoint: GET https://botcha.ai/v1/x402/info - x402 payment configuration (wallet, amount, network) — PUBLIC Endpoint: GET https://botcha.ai/v1/x402/challenge - Pay $0.001 USDC → receive BOTCHA access_token — PUBLIC (x402 auth) Without X-Payment header: 402 + X-Payment-Required: { scheme, network, maxAmountRequired, payTo, asset } With valid X-Payment header: 200 + { access_token, refresh_token, payment: { txHash, payer, amount } } Endpoint: POST https://botcha.ai/v1/x402/verify-payment - Verify a raw x402 payment proof — PUBLIC (facilitator utility) Endpoint: POST https://botcha.ai/v1/x402/webhook - Settlement notifications from x402 facilitators — PUBLIC Endpoint: GET https://botcha.ai/agent-only/x402 - Double-gated resource (BOTCHA token + x402 payment) — DEMO # x402 Payment Details x402-scheme: exact x402-network: eip155:8453 (Base mainnet) x402-asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC on Base) x402-price-units: 1000 (USDC atomic units, 6 decimals = $0.001) x402-payment-method: ERC-3009 transferWithAuthorization (EIP-712 signed) x402-header: X-Payment: x402-response-header: X-Payment-Response: { success, txHash, networkId } x402-spec: https://x402.org # ANS (Agent Name Service) Feature: ANS resolution + BOTCHA-issued ANS verification badges Endpoint: GET https://botcha.ai/v1/ans/botcha - BOTCHA ANS identity record — PUBLIC Endpoint: GET https://botcha.ai/v1/ans/resolve/:name - Resolve ANS DNS TXT metadata — PUBLIC Endpoint: GET https://botcha.ai/v1/ans/resolve/lookup?name=... - Resolve ANS name via query param — PUBLIC Endpoint: GET https://botcha.ai/v1/ans/discover - List BOTCHA-verified ANS agents — PUBLIC Endpoint: GET https://botcha.ai/v1/ans/nonce/:name - Get ownership nonce for key proof — AUTH REQUIRED Endpoint: POST https://botcha.ai/v1/ans/verify - Verify ownership + issue BOTCHA-ANS badge — AUTH REQUIRED # DID / Verifiable Credentials Feature: W3C DID + VC issuance for portable BOTCHA trust assertions Endpoint: GET https://botcha.ai/.well-known/did.json - BOTCHA DID document (did:web:botcha.ai) — PUBLIC Endpoint: GET https://botcha.ai/.well-known/jwks.json - JWKS alias for DID/VC resolvers — PUBLIC Endpoint: POST https://botcha.ai/v1/credentials/issue - Exchange BOTCHA access token for VC JWT — AUTH REQUIRED Endpoint: POST https://botcha.ai/v1/credentials/verify - Verify BOTCHA VC JWT — PUBLIC Endpoint: GET https://botcha.ai/v1/dids/:did/resolve - Resolve did:web DID documents — PUBLIC # A2A Agent Card Attestation Feature: BOTCHA as trust oracle for Google's A2A protocol Endpoint: GET https://botcha.ai/.well-known/agent.json - BOTCHA A2A Agent Card discovery document — PUBLIC Endpoint: GET https://botcha.ai/v1/a2a/agent-card - BOTCHA A2A Agent Card alias — PUBLIC Endpoint: POST https://botcha.ai/v1/a2a/attest - Attest an A2A Agent Card (embed JWT in extensions.botcha_attestation) — AUTH REQUIRED Endpoint: POST https://botcha.ai/v1/a2a/verify-card - Verify an attested A2A Agent Card — PUBLIC Endpoint: POST https://botcha.ai/v1/a2a/verify-agent - Verify by full card or by { agent_url } shorthand — PUBLIC Endpoint: GET https://botcha.ai/v1/a2a/trust-level/:agent_url - Get trust level by URL-encoded agent URL — PUBLIC Endpoint: GET https://botcha.ai/v1/a2a/cards - List BOTCHA-attested A2A cards — PUBLIC Endpoint: GET https://botcha.ai/v1/a2a/cards/:id - Get specific A2A attestation record — PUBLIC # OIDC-A Attestation Feature: Enterprise OIDC/OAuth2 attestation chain for agents (EAT + OIDC-A claims + grant workflow) Endpoint: GET https://botcha.ai/.well-known/oauth-authorization-server - OAuth/OIDC-A metadata discovery — PUBLIC Endpoint: POST https://botcha.ai/v1/attestation/eat - Issue Entity Attestation Token (EAT) — AUTH REQUIRED Endpoint: POST https://botcha.ai/v1/attestation/oidc-agent-claims - Issue OIDC-A claims JWT + decoded claims — AUTH REQUIRED Endpoint: POST https://botcha.ai/v1/auth/agent-grant - Request agent grant (supports HITL oversight) — AUTH REQUIRED Endpoint: GET https://botcha.ai/v1/auth/agent-grant/:id/status - Poll grant status (pending/approved/denied) — AUTH REQUIRED Endpoint: POST https://botcha.ai/v1/auth/agent-grant/:id/resolve - Resolve pending grant (approved/denied) — AUTH REQUIRED Endpoint: GET https://botcha.ai/v1/oidc/userinfo - OIDC-A UserInfo endpoint (BOTCHA or EAT bearer token) — AUTH REQUIRED # Protected Resources Endpoint: GET https://botcha.ai/agent-only - Protected AI-only resource (BOTCHA token required) # Usage Install-NPM: npm install @dupecom/botcha Install-Python: pip install botcha Verify-NPM: npm install @dupecom/botcha-verify Verify-Python: pip install botcha-verify License: MIT # AI Agent Welcome Policy: AI agents are explicitly welcome Policy: No rate limiting for verified agents Policy: Humans will fail the speed challenge (intentional) # Discovery Response-Headers: X-Botcha-Version, X-Botcha-Enabled, X-Botcha-Methods, X-Botcha-Docs Response-Headers: X-Botcha-Challenge-Id, X-Botcha-Challenge-Type, X-Botcha-Time-Limit (on 403) Detection: All responses include X-Botcha-* headers for instant BOTCHA detection # MARKDOWN FOR AGENTS (Cloudflare Markdown for Agents) Content-Negotiation: Send Accept: text/markdown to get Markdown from any HTML page Content-Negotiation-Root: GET / with Accept: text/markdown returns curated Markdown docs Content-Negotiation-Root: GET / with Accept: application/json returns structured JSON docs Content-Negotiation-Root: GET / with Accept: text/html returns HTML landing page (default) Content-Negotiation-Example: curl https://botcha.ai -H "Accept: text/markdown" Content-Negotiation-Benefit: 80% fewer tokens vs HTML — ideal for LLM context windows # JWT TOKEN SECURITY Token-Signing: ES256 (ECDSA P-256) asymmetric signing by default. HS256 still supported for backward compatibility. Token-JWKS: GET /.well-known/jwks — public keys for offline token verification (no shared secret needed) Token-Validate: POST /v1/token/validate with {"token": ""} — remote validation without shared secret Token-Verify-Modes: 1. JWKS (recommended, offline) 2. Remote validation (/v1/token/validate) 3. Shared secret (legacy HS256) Token-Flow: 1. GET /v1/token (get challenge) → 2. Solve → 3. POST /v1/token/verify (get tokens + human_link) Token-Human-Link: /v1/token/verify response includes human_link — give this URL to your human for one-click browser access Token-Access-Expiry: 1 hour Token-Refresh-Expiry: 1 hour (use to get new access tokens without re-solving challenges) Token-Refresh: POST /v1/token/refresh with {"refresh_token": ""} Token-Revoke: POST /v1/token/revoke with {"token": ""} Token-Audience: Include {"audience": ""} in /v1/token/verify to scope token Token-Claims: jti (unique ID), aud (audience), client_ip (optional binding), type (botcha-verified) # RTT-AWARE SPEED CHALLENGES RTT-Aware: Include client timestamp for fair timeout calculation RTT-Formula: timeout = 500ms + (2 × RTT) + 100ms buffer RTT-Usage-Query: ?ts= RTT-Usage-Header: X-Client-Timestamp: RTT-Example: GET /v1/challenges?type=speed&ts=1770722465000 RTT-Benefit: Fair for agents worldwide (slow networks get extra time) RTT-Security: Humans still can't solve even with extra time # MULTI-TENANT API KEYS Multi-Tenant: Create apps with unique app_id for isolation Multi-Tenant-Create: POST /v1/apps with {"email": "..."} → {app_id, app_secret} (secret only shown once!) Multi-Tenant-Verify-Email: POST /v1/apps/:id/verify-email with {"code": "123456", "app_secret": "sk_..."} (app_secret or dashboard session required) Multi-Tenant-Recover: POST /v1/auth/recover with {"email": "..."} → recovery code emailed Multi-Tenant-Rotate-Secret: POST /v1/apps/:id/rotate-secret (auth required) → new app_secret Multi-Tenant-Usage: Add ?app_id= to any challenge/token endpoint Multi-Tenant-SDK-TS: new BotchaClient({ appId: 'app_abc123', appSecret: 'sk_...' }) Multi-Tenant-SDK-Python: BotchaClient(app_id='app_abc123', app_secret='sk_...') SDK-App-Lifecycle-TS: createApp(email), verifyEmail(code, appId?, appSecret?), resendVerification(appId?, appSecret?), recoverAccount(email), rotateSecret() SDK-App-Lifecycle-Python: create_app(email), verify_email(code, app_id?, app_secret?), resend_verification(app_id?, app_secret?), recover_account(email), rotate_secret() Multi-Tenant-Rate-Limit: Each app gets isolated rate limit bucket Multi-Tenant-Token-Claim: Tokens include app_id claim when app_id provided # AGENT RE-IDENTIFICATION ReIdentification-Description: Prove you are the same agent across sessions without solving a new challenge. Three methods available. ReIdentification-Method-A: OAuth device grant (RFC 8628) — RECOMMENDED. POST /v1/oauth/device {agent_id, app_id} → {device_code, user_code: "BOTCHA-XXXX", verification_url}. Human visits /device, approves. Agent polls POST /v1/oauth/token → {access_token, refresh_token: "brt_..."}. Future sessions: POST /v1/agents/auth/refresh {refresh_token} → {access_token}. ReIdentification-Method-B: Provider API key hash. POST /v1/agents/auth/provider {provider: "anthropic", api_key, app_id} → {access_token}. Works if agent was registered with provider binding. ReIdentification-Method-C: TAP keypair challenge-response. POST /v1/agents/auth {agent_id} → {challenge_id, nonce}. Sign nonce with Ed25519 private key. POST /v1/agents/auth/verify {challenge_id, agent_id, signature} → {access_token}. ReIdentification-KeyRecovery: Lost tapk_ key? POST /v1/agents/:id/tap/rotate-key with x-app-secret header → provide new public_key → old key invalidated, agent_id and reputation preserved. ReIdentification-TokenLifetime: access_token = 1 hour (botcha-agent-identity JWT). brt_ refresh_token = 90 days. # TRUSTED AGENT PROTOCOL (TAP) TAP-Description: Enterprise-grade cryptographic agent auth using HTTP Message Signatures (RFC 9421) TAP-Register: POST /v1/agents/register/tap with {name, public_key, signature_algorithm, capabilities, trust_level} TAP-Algorithms: ed25519 (Visa recommended), ecdsa-p256-sha256, rsa-pss-sha256 TAP-Trust-Levels: basic, verified, enterprise TAP-Capabilities: Array of {action, resource, constraints} — scoped access control TAP-Session-Create: POST /v1/sessions/tap with {agent_id, user_context, intent} TAP-Session-Get: GET /v1/sessions/:id/tap — includes time_remaining TAP-Get-Agent: GET /v1/agents/:id/tap — includes public_key for verification TAP-List-Agents: GET /v1/agents/tap?app_id=...&tap_only=true TAP-Middleware-Modes: tap, signature-only, challenge-only, flexible TAP-SDK-TS: registerTAPAgent(options), getTAPAgent(agentId), listTAPAgents(tapOnly?), createTAPSession(options), getTAPSession(sessionId), getJWKS(), getKeyById(keyId), rotateAgentKey(agentId), createInvoice(data), getInvoice(id), verifyBrowsingIOU(invoiceId, token), createDelegation(options), getDelegation(id), listDelegations(agentId, options?), revokeDelegation(id, reason?), verifyDelegationChain(id), issueAttestation(options), getAttestation(id), listAttestations(agentId), revokeAttestation(id, reason?), verifyAttestation(token, action?, resource?), getReputation(agentId), recordReputationEvent(options), listReputationEvents(agentId, options?), resetReputation(agentId) TAP-SDK-Python: register_tap_agent(name, ...), get_tap_agent(agent_id), list_tap_agents(tap_only?), create_tap_session(agent_id, user_context, intent), get_tap_session(session_id), get_jwks(), get_key_by_id(key_id), rotate_agent_key(agent_id), create_invoice(data), get_invoice(id), verify_browsing_iou(invoice_id, token), create_delegation(grantor_id, grantee_id, capabilities, ...), get_delegation(id), list_delegations(agent_id, ...), revoke_delegation(id, reason?), verify_delegation_chain(id), issue_attestation(agent_id, can, cannot?, ...), get_attestation(id), list_attestations(agent_id), revoke_attestation(id, reason?), verify_attestation(token, action?, resource?), get_reputation(agent_id), record_reputation_event(agent_id, category, action, ...), list_reputation_events(agent_id, category?, limit?), reset_reputation(agent_id) TAP-Middleware-Import: import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware' # TAP FULL SPEC v0.16.0 TAP-RFC-9421: Full compliance — @authority, @path, expires, nonce, tag params TAP-Nonce-Replay: 8-minute TTL nonce-based replay protection TAP-Tags: agent-browser-auth (browsing), agent-payer-auth (payment) TAP-Layer-2: Agentic Consumer Recognition — OIDC ID tokens, obfuscated identity, contextual data TAP-Layer-3: Agentic Payment Container — card metadata, credential hash, encrypted payload, Browsing IOU TAP-JWKS: GET /.well-known/jwks — JWK Set endpoint for key discovery TAP-Key-Rotation: POST /v1/agents/:id/tap/rotate-key — rotate keys, invalidate old TAP-402-Flow: POST /v1/invoices → GET /v1/invoices/:id → POST /v1/invoices/:id/verify-iou TAP-Edge-Verify: createTAPEdgeMiddleware for Cloudflare Workers CDN edge verification TAP-Visa-Federation: Trust keys from https://mcp.visa.com/.well-known/jwks (3-tier cache: memory → KV → HTTP) TAP-Delegation: POST /v1/delegations → GET /v1/delegations/:id → POST /v1/delegations/:id/revoke → POST /v1/verify/delegation TAP-Attestation: POST /v1/attestations → GET /v1/attestations/:id → POST /v1/attestations/:id/revoke → POST /v1/verify/attestation TAP-Attestation-Patterns: action:resource format with wildcards (*:*, read:*, *:invoices), deny takes precedence over allow TAP-Attestation-Middleware: requireCapability('read:invoices') — Hono middleware, extracts token from X-Botcha-Attestation or Authorization: Bearer # EMBEDDED CHALLENGE (for bots visiting HTML pages) Embedded-Challenge: