{"openapi":"3.1.0","info":{"title":"Agent Credential Broker API","version":"0.0.0-step9","description":"Delegated tool execution API. Agents use short-lived broker JWTs; credentials stay in the vault. Hero endpoint: POST /v1/tools/execute."},"servers":[{"url":"http://localhost:3001","description":"Local dev"}],"tags":[{"name":"health"},{"name":"tools"},{"name":"connections"},{"name":"approvals"},{"name":"agents"},{"name":"api-keys"},{"name":"broker"},{"name":"audit"},{"name":"billing"},{"name":"webhooks"}],"paths":{"/health":{"get":{"tags":["health"],"summary":"Liveness and config hints","responses":{"200":{"description":"OK"}}}},"/openapi.json":{"get":{"tags":["health"],"summary":"OpenAPI document","responses":{"200":{"description":"This document"}}}},"/v1/tools/execute":{"post":{"tags":["tools"],"summary":"Delegated tool execution (hero)","description":"Policy-checked server-side execute. Returns scrubbed results only — never OAuth tokens or secrets.","security":[{"brokerJwt":[]},{"controlPlaneKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool_name","arguments"],"properties":{"tool_name":{"type":"string"},"connected_account_id":{"type":"string","format":"uuid","nullable":true},"secret_item_id":{"type":"string","format":"uuid","nullable":true},"arguments":{"type":"object","additionalProperties":true},"idempotency_key":{"type":"string","nullable":true},"approval_id":{"type":"string","format":"uuid","nullable":true},"agent_app_id":{"type":"string","format":"uuid","description":"Required when authenticating with bk_* API key"}}}}}},"responses":{"200":{"description":"Tool result"},"401":{"description":"unauthorized"},"403":{"description":"policy_denied"},"409":{"description":"approval_required"},"422":{"description":"invalid_tool_args"},"429":{"description":"rate_limited"},"502":{"description":"upstream_error"},"503":{"description":"vault_unavailable"}}}},"/v1/tools/invocations/{invocation_id}/continue":{"post":{"tags":["tools"],"summary":"Resume execution after human approval","security":[{"brokerJwt":[]},{"controlPlaneKey":[]}],"parameters":[{"name":"invocation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tool result"},"409":{"description":"approval_pending"},"429":{"description":"rate_limited"}}}},"/v1/broker/token":{"post":{"tags":["broker"],"summary":"Mint short-lived broker JWT for an agent","security":[{"controlPlaneKey":[]}],"responses":{"200":{"description":"JWT issued"},"429":{"description":"rate_limited"}}}},"/v1/connections/oauth/start":{"post":{"tags":["connections"],"summary":"Start OAuth connect (PKCE)","security":[{"operatorSession":[]}],"responses":{"200":{"description":"authorize_url + state"}}}},"/v1/connections/oauth/callback":{"get":{"tags":["connections"],"summary":"OAuth callback — stores encrypted tokens","responses":{"200":{"description":"connected_account_id only"}}}},"/v1/connections":{"get":{"tags":["connections"],"summary":"List connected accounts for the signed-in user","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Connection handles"}}}},"/v1/connections/{id}":{"delete":{"tags":["connections"],"summary":"Revoke a connection","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Revoked; emits connection.revoked webhook"}}}},"/v1/approvals":{"get":{"tags":["approvals"],"summary":"List pending approvals","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Pending queue"}}}},"/v1/approvals/{id}/decide":{"post":{"tags":["approvals"],"summary":"Approve or deny a pending tool call","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Decision recorded"}}}},"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"List webhook endpoints","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Endpoints (secret prefix only)"}}},"post":{"tags":["webhooks"],"summary":"Create webhook endpoint","description":"Signing secret returned once (whsec_…); stored encrypted at rest.","security":[{"operatorSession":[]}],"responses":{"201":{"description":"Created"}}}},"/v1/webhooks/{id}/test":{"post":{"tags":["webhooks"],"summary":"Send webhook.test event","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Delivery attempted"}}}},"/v1/billing/status":{"get":{"tags":["billing"],"summary":"Stripe metering mode and plan-match preview","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Status"}}}},"/v1/billing/plans":{"get":{"tags":["billing"],"summary":"Locked public plan packaging","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Plans"}}}},"/v1/billing/invoice-preview":{"post":{"tags":["billing"],"summary":"Monthly invoice + customer notice (test mode)","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Preview"}}}},"/v1/billing/finalize-period":{"post":{"tags":["billing"],"summary":"Apply one-time plan-match consumption (test mode)","security":[{"operatorSession":[]}],"responses":{"200":{"description":"Finalized"}}}}},"components":{"securitySchemes":{"brokerJwt":{"type":"http","scheme":"bearer","description":"Short-lived agent JWT (aud=broker)"},"controlPlaneKey":{"type":"http","scheme":"bearer","description":"Control-plane API key bk_live_* or bk_test_*"},"operatorSession":{"type":"http","scheme":"bearer","description":"Auth0 access token + X-Broker-Tenant-Id header"}},"schemas":{"Error":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","policy_denied","not_found","approval_required","invalid_tool_args","rate_limited","upstream_error","vault_unavailable"]},"message":{"type":"string"}}}}}}}}