paybondpaybond
Sign in

Paybond API documentation

Authentication, versioning, idempotency, and error rules shared by Harbor, Gateway, and Signal.

Service references

Three public API surfaces. Each reference includes the interactive contract plus related SDK guidance.

Paybond exposes three HTTP surfaces: Harbor, Gateway, and Signal. Together, they cover settlement lifecycle management, authentication and administrative workflows, and signed standing artifacts.

All authenticated API calls are scoped to exactly one organization. Requests cannot read or write across organizations, and the authenticated token remains the source of truth for scope. For the platform model behind that behavior, see Tenant model.

Use this page for the rules shared across all three services. Use the service-specific references for request and response details.

Hosted origins

SurfaceURLRole
Gatewayhttps://api.paybond.aiPublic API front door for Kit sessions, Harbor and Signal proxy routes, auth, protocol verification, and admin workflows
Consolehttps://console.paybond.aiOperator UI and API key management

Prefix HTTP requests with the Gateway origin (for example GET https://api.paybond.ai/v1/auth/principal). Route paths carry their own version segment (/v1/…, /harbor/…, /protocol/…); do not treat /v1 as the Gateway base URL.

Kit SDKs default to https://api.paybond.ai. Override with gatewayBaseUrl / gateway_base_url on Paybond.open(...), or set PAYBOND_GATEWAY_URL / PAYBOND_GATEWAY_BASE_URL for scaffold helpers and the MCP server. See Endpoints & environments.

Paybond is not a model-provider LLM inference proxy. Model inference stays on OpenAI, Anthropic, Gemini, or your chosen host; Paybond governs delegated spend at the tool boundary via Kit.

Gateway also includes the v2 protocol verification and discovery surface for delegated agent workflows:

  • POST /protocol/v2/mandates
  • POST /protocol/v2/mandates/verify
  • POST /protocol/v2/recognition/verify
  • GET /protocol/v2/receipts/{receipt_id}
  • POST /protocol/v2/receipts/verify
  • GET /.well-known/agent-card.json
  • GET /protocol/v2/a2a/task-contracts

Signal exposes organization-scoped signed artifacts rather than a shared public reputation plane:

  • GET /reputation/{operator_did} returns a signed operator receipt
  • GET /signal/v1/portfolio/signed-export returns a signed tenant portfolio artifact

Authentication

Every protected request to Harbor or Gateway must carry one of the following:

  1. A session Bearer JWT minted by the Gateway sign-in endpoints (POST /v1/public/auth/login/start + POST /v1/public/auth/challenges/verify, or POST /v1/auth/sso/*). Used by the admin console and browser-originated workflows.
  2. A service-account API key sent to Gateway-hosted SDK surfaces such as GET /v1/auth/principal, POST /verify, and POST /harbor/*. Gateway derives any upstream Harbor credentials internally.
  3. A dedicated download JWT (aud = paybond-audit-export-download) for signed bundle downloads. Issued alongside the create/get responses for audit exports and must not be mixed with session tokens.

In every case the token carries a tid claim (tenant realm) that is the authorization identity. Unauthenticated identifiers in the request body (tenant_id, org_id) are treated only as hints and must match the token. Kit SDKs do this automatically. When calling the HTTP surfaces directly, you are responsible for attaching Authorization: Bearer … and, where required, the matching x-tenant-id header.

Versioning

  • HTTP paths carry their version in the path (/v1/…, /policy/v1/…, /signal/v1/…). Breaking changes bump that segment and ship alongside the previous version until the deprecation window closes.
  • Signed artifacts (Signal receipts, portfolio snapshots, audit export manifests) carry an independent schema_version integer plus an artifact_version or receipt_version string. Parsers must reject unknown schema_version values before attempting signature verification.
  • Harbor intent signing is versioned inside the signed payload itself. Offline signers should pin to a specific signing payload version supported by their SDK or integration.

The public API references served under /docs/api/harbor, /docs/api/gateway, and /docs/api/signal pin the current major version for each service. Supporting schema fragments may version independently, but the public docs stay centered on the service pages rather than raw schema files.

Idempotency

Mutating Harbor POST routes honor an optional idempotency-key header (1–256 chars). The key is scoped per authenticated tenant and HTTP operation. Reusing a key with a different request body returns 409 Conflict. Reusing it with the same body replays the original response.

Currently honored by:

  • POST /intents
  • POST /intents/{intent_id}/fund
  • POST /intents/{intent_id}/evidence
  • POST /intents/{intent_id}/settlement/confirm

For Harbor-specific route coverage, see the Harbor API reference. Policy-registry POSTs do not honor idempotency keys today, so use natural-key reads (GET …/versions) to detect existing drafts before retrying.

Gateway and Signal endpoints are read-only or status/export oriented and do not require client-supplied idempotency keys today.