{"openapi":"3.1.0","info":{"title":"6529 ZK API","version":"0.1.0","summary":"Zero-knowledge proof service for 6529 ecosystem profile factors.","description":"Public API for discovering supported proof types, fetching Merkle roots and proof rows, serving circuit artifacts, and verifying Groth16 proofs."},"servers":[{"url":"https://zkyc.solutions","description":"production service"}],"tags":[{"name":"Discovery"},{"name":"Auth"},{"name":"Proofs"},{"name":"Artifacts"},{"name":"Partners"},{"name":"Billing"},{"name":"Operations"}],"paths":{"/api/meta":{"get":{"tags":["Discovery"],"summary":"Get public integration metadata","responses":{"200":{"description":"Service metadata and proof catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicServiceMeta"}}}}}}},"/api/openapi":{"get":{"tags":["Discovery"],"summary":"Get this OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/health":{"get":{"tags":["Discovery"],"summary":"Get operational health","responses":{"200":{"description":"Healthy or degraded service state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Database or artifact health check failed"}}}},"/api/auth/wallet/challenge":{"post":{"tags":["Auth"],"summary":"Create a wallet signature challenge","description":"Returns an EIP-191 message for the browser wallet to sign before requesting a wallet-bound proof lookup JWT.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletChallengeRequest"}}}},"responses":{"200":{"description":"Wallet challenge issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletChallengeResponse"}}}},"400":{"description":"Invalid address or chain id"},"429":{"description":"Rate limited"},"500":{"description":"Wallet challenge secret missing"}}}},"/api/auth/wallet/verify":{"post":{"tags":["Auth"],"summary":"Verify a wallet signature and issue proof JWT","description":"Verifies the signed challenge and returns a short-lived bearer JWT scoped to the signing wallet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletVerifyRequest"}}}},"responses":{"200":{"description":"Wallet proof lookup token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletVerifyResponse"}}}},"400":{"description":"Invalid or expired challenge/signature"},"429":{"description":"Rate limited"},"500":{"description":"Wallet auth secret missing"}}}},"/api/zk":{"get":{"tags":["Proofs"],"summary":"Get latest root or a Merkle proof row","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["tdh_range","level_range","card_ownership","any_card","n_of_m_cards","vpn_access_v1"]}},{"name":"key","in":"query","required":false,"schema":{"type":"string"},"description":"Lookup key. Omit to fetch the latest Merkle root."},{"name":"root","in":"query","required":false,"schema":{"type":"string"},"description":"Optional retained Merkle root for proof lookup."}],"security":[{"walletProofJwt":[],"partnerApiKey":[]},{"walletProofJwt":[]},{}],"responses":{"200":{"description":"Merkle root or proof lookup result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MerkleRoot"},"error":{"type":"string"}}},{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MerkleProof"},"error":{"type":"string"}}}]}}}},"400":{"description":"Invalid or missing proof type"},"401":{"description":"Missing proof lookup authorization"},"403":{"description":"Proof lookup not authorized for this key"},"404":{"description":"Root or proof not found"}}},"post":{"tags":["Proofs"],"summary":"Verify a Groth16 proof","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"Malformed verification request"},"429":{"description":"Rate limited"}}}},"/api/artifacts/{path}":{"get":{"tags":["Artifacts"],"summary":"Download a circuit artifact","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Artifact bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid artifact path"},"404":{"description":"Artifact not found"}}}},"/api/admin/partners":{"get":{"tags":["Partners"],"summary":"List partner accounts and recent usage","security":[{"adminBearer":[]}],"responses":{"200":{"description":"Partner list"},"401":{"description":"Missing or invalid admin token/session"},"500":{"description":"Partner tables are unavailable or query failed"}}},"post":{"tags":["Partners"],"summary":"Create a partner account and optionally issue an API key","security":[{"adminBearer":[]}],"responses":{"201":{"description":"Partner created; plaintext API key returned once"},"400":{"description":"Invalid partner payload"},"401":{"description":"Missing or invalid admin token/session"},"500":{"description":"Partner create failed"}}}},"/api/admin/partners/{partnerId}/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create a Stripe Checkout subscription session for a partner","security":[{"adminBearer":[]}],"parameters":[{"name":"partnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Partner UUID or slug."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout URL created"},"400":{"description":"Invalid checkout request"},"401":{"description":"Missing or invalid admin token/session"},"404":{"description":"Partner not found"},"503":{"description":"Stripe secret or price ID missing"}}}},"/api/admin/partners/{partnerId}/billing/portal":{"post":{"tags":["Billing"],"summary":"Create a Stripe Customer Portal session for a partner","security":[{"adminBearer":[]}],"parameters":[{"name":"partnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Partner UUID or slug."}],"responses":{"200":{"description":"Portal URL created"},"401":{"description":"Missing or invalid admin token/session"},"404":{"description":"Partner not found"},"409":{"description":"Partner does not have a Stripe customer yet"},"503":{"description":"Stripe secret missing"}}}},"/api/billing/plans":{"get":{"tags":["Billing"],"summary":"List commercial billing plans and Stripe readiness","responses":{"200":{"description":"Billing plans and configuration state"}}}},"/api/webhooks/stripe":{"post":{"tags":["Billing"],"summary":"Stripe webhook endpoint","description":"Verifies Stripe signatures using STRIPE_WEBHOOK_SECRET and syncs subscription status back to partner records.","responses":{"200":{"description":"Webhook received"},"400":{"description":"Missing or invalid Stripe signature"},"503":{"description":"Stripe webhook secret missing"}}}},"/api/sync/tdh":{"post":{"tags":["Operations"],"summary":"Trigger TDH sync","security":[{"syncBearer":[]}],"responses":{"200":{"description":"TDH sync completed"},"401":{"description":"Missing or invalid sync token"},"429":{"description":"Rate limited"},"500":{"description":"Sync failed"}}}},"/api/sync/level":{"post":{"tags":["Operations"],"summary":"Trigger 6529 level sync","security":[{"syncBearer":[]}],"responses":{"200":{"description":"6529 level sync completed"},"401":{"description":"Missing or invalid sync token"},"429":{"description":"Rate limited"},"500":{"description":"Sync failed"}}}},"/api/sync/cards":{"post":{"tags":["Operations"],"summary":"Trigger card ownership sync","security":[{"syncBearer":[]}],"responses":{"200":{"description":"Card sync completed"},"401":{"description":"Missing or invalid sync token"},"429":{"description":"Rate limited"},"500":{"description":"Sync failed"}}}}},"components":{"securitySchemes":{"walletProofJwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Wallet-bound proof lookup JWT for private lookup keys."},"partnerApiKey":{"type":"apiKey","in":"header","name":"X-ZKYC-API-Key","description":"Partner API key used for paid access control, usage attribution, and metering."},"adminBearer":{"type":"http","scheme":"bearer","description":"ADMIN_UI_KEY for partner management automation."},"syncBearer":{"type":"http","scheme":"bearer","description":"Operator-only SYNC_API_KEY."}},"schemas":{"PublicServiceMeta":{"type":"object","required":["service","version","capabilities","endpoints","proofCatalog"],"properties":{"service":{"type":"string"},"version":{"type":"string"},"environment":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"capabilities":{"type":"object","properties":{"proofTypes":{"type":"array","items":{"type":"string","enum":["tdh_range","level_range","card_ownership","any_card","n_of_m_cards","vpn_access_v1"]}},"rootRetentionDays":{"type":"integer"}}},"endpoints":{"type":"object","additionalProperties":{"type":"string"}},"proofCatalog":{"type":"array","items":{"$ref":"#/components/schemas/ProofCatalogEntry"}}}},"ProofCatalogEntry":{"type":"object","required":["type","label","treeProofType","availability","lookupKey"],"properties":{"type":{"type":"string","enum":["tdh_range","level_range","card_ownership","any_card","n_of_m_cards","vpn_access_v1"]},"label":{"type":"string"},"treeProofType":{"type":"string","enum":["tdh_range","level_range","card_ownership","any_card","n_of_m_cards","vpn_access_v1"]},"availability":{"type":"string","enum":["live","derived","dev"]},"purpose":{"type":"string"},"lookupKey":{"type":"object"},"publicSignals":{"type":"array","items":{"type":"string"}}}},"WalletChallengeRequest":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"Wallet address that will sign the challenge."},"chainId":{"type":"integer","default":1,"description":"Optional wallet chain id to display in the message."}}},"WalletChallengeResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["address","chainId","message","challengeToken","expiresAt"],"properties":{"address":{"type":"string"},"chainId":{"type":"integer"},"message":{"type":"string"},"challengeToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"error":{"type":"string"}}},"WalletVerifyRequest":{"type":"object","required":["challengeToken","message","signature"],"properties":{"challengeToken":{"type":"string"},"message":{"type":"string"},"signature":{"type":"string","description":"EIP-191/personal_sign signature for the challenge message."},"address":{"type":"string","description":"Optional wallet address; must match the challenge if provided."}}},"WalletVerifyResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["address","token","tokenType","expiresAt"],"properties":{"address":{"type":"string"},"token":{"type":"string"},"tokenType":{"type":"string","enum":["Bearer"]},"expiresAt":{"type":"string","format":"date-time"}}},"error":{"type":"string"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","error"]},"service":{"type":"string"},"sync":{"type":"array","items":{"$ref":"#/components/schemas/SyncState"}}}},"SyncState":{"type":"object","properties":{"proofType":{"type":"string"},"lastSyncAt":{"type":["string","null"],"format":"date-time"},"entryCount":{"type":"integer"},"status":{"type":"string"},"errorMessage":{"type":["string","null"]},"updatedAt":{"type":"string","format":"date-time"}}},"MerkleRoot":{"type":"object","properties":{"root":{"type":"string"},"depth":{"type":"integer"},"entryCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"metadata":{"type":"object"}}},"MerkleProof":{"type":"object","properties":{"proof_type":{"type":"string"},"lookup_key":{"type":"string"},"leaf":{"type":"string"},"path_elements":{"type":"array","items":{"type":"string"}},"path_indices":{"type":"array","items":{"type":"integer"}},"root":{"type":"string"},"metadata":{"type":"object"}}},"VerifyRequest":{"type":"object","required":["proofType","proof","publicSignals"],"properties":{"proofType":{"type":"string","enum":["tdh_range","level_range","card_ownership","any_card","n_of_m_cards","vpn_access_v1"]},"proof":{"type":"object"},"publicSignals":{"type":"array","items":{"type":"string"}}}},"VerifyResponse":{"type":"object","properties":{"valid":{"type":"boolean"},"reason":{"type":"string"}}},"BillingCheckoutRequest":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","growth","pro","enterprise"],"description":"Plan to sell through Stripe Checkout."},"successUrl":{"type":"string","description":"Optional Checkout success URL override."},"cancelUrl":{"type":"string","description":"Optional Checkout cancel URL override."},"customerEmail":{"type":"string","description":"Optional billing email for the Stripe Customer."}}}}}}