# Paybond API documentation

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

> **Product surfaces:** If the branded names are new, start with [Product surfaces](../platform/product-surfaces.md). **Harbor** is the *agent transaction engine* (signed intents, escrow, evidence, release/refund). **Signal** is *standing & reputation* (signed receipts and portfolio exports). **Gateway** is the API front door — it proxies Harbor and Signal routes and hosts Kit session/auth; it is not a separate marketing product.

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](../platform/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

| Surface | URL | Role |
| --- | --- | --- |
| **Gateway** | `https://api.paybond.ai` | Public API front door for Kit sessions, Harbor and Signal proxy routes, auth, protocol verification, and admin workflows |
| **Console** | `https://console.paybond.ai` | Operator 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.

Harbor does not expose a separate public origin. Use the Gateway Harbor proxy at `https://api.paybond.ai/harbor/…`.

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](../kit/endpoints.md).

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 /.well-known/agent-receipt-v1.json`
- `GET /protocol/v2/agent-receipts/{receipt_id}`
- `GET /protocol/v2/agent-receipts`
- `POST /protocol/v2/agent-receipts/verify`
- `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/*`). Signed with EdDSA; verify via `GET /.well-known/jwks.json`. 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 (`signing_version` on create, `EvidenceSignV1.version` on evidence). Supported create envelopes for fundable intents are **signing v6** (raw `predicate_dsl`) and **signing v7** (`policy_binding`), both requiring `payee_pubkey` bound in the principal signature. Signing v4/v5 are deprecated and rejected for fundable intents and in live environments. Offline signers should pin to a specific signing payload version supported by their SDK or integration.
- Harbor, Kit, and ledger signing bytes use **bincode 2** (`bincode::config::standard()` / `encode_wire`). This replaced bincode 1 in 2026-06; signatures from older Kit releases are not valid after Harbor deploy. Evidence binding uses `EvidenceSignV1.version = 2`; ledger row bodies use `format_version = 2`.

### Signed artifact version matrix

| Artifact | `kind` / envelope | `schema_version` | `receipt_version` | Signing |
| --- | --- | --- | --- | --- |
| Protocol authorization receipt | `paybond.protocol_authorization_receipt_v1` | `1` | `"1"` | `ed25519-sha256-json-v1` (Gateway) |
| Protocol settlement receipt | `paybond.protocol_settlement_receipt_v1` | `1` | `"1"` | `ed25519-sha256-json-v1` (Gateway) |
| Agent receipt | `paybond.agent_receipt_v1` | `1` | `"1"` | `ed25519-sha256-json-v1` (Gateway) |
| Agent recognition proof | `paybond.agent_recognition_proof_v1` | `1` | — | `ed25519-sha256-json-v1` (tenant/agent key) |

Agent receipt schema discovery: `GET /.well-known/agent-receipt-v1.json`. Normative spec: [Agent receipts](../platform/agent-receipt.md). Product guide: [Agent Receipt Standard (ARS)](/guides/agent-receipt-standard).

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](./harbor). 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.

## Related

- [Endpoints & environments](../kit/endpoints.md) — Gateway and Console URLs, env overrides, not a model-provider proxy.
- [Harbor predicate DSL](./harbor-predicate-dsl) — evidence evaluation contract.
- [Kit documentation](../kit/index) — TypeScript and Python SDK wrappers.
- [Platform overview](../platform/index) — intent lifecycle, tenant model, and operational surfaces.