paybondpaybond
Sign in

Onboarding

Paybond Kit onboarding for partner engineering teams — security model, tenant scope, and first-integration checklist.

Onboarding — Paybond Kit for partner engineering teams

This guide assumes you have a Paybond gateway URL, Harbor base URL, and a service-account API key (paybond_sk_…) issued for one tenant realm.

Current SDK boundary: the Kit is the integration surface for Harbor execution flows, tenant-scoped ledger provenance reads, and read-only Signal reputation/analytics APIs. Signal support now includes tenant-bound receipt, portfolio summary, explanation, and review-status reads through the gateway.

Signal review-status reads now also carry the policy boundary around the score: maturity tiers, shadow annotations, and replay / appeal friction. These fields are additive workflow metadata only; they do not change score_version = 1.0.

Security model (read this first)

  1. Tenant scope is derived from credentials, not from ad-hoc string headers you invent at runtime. With a supported gateway, POST /v1/auth/harbor-access returns tenant_id; the Kit binds every Harbor call to that realm.
  2. Never reuse a HarborClient across tenants. Create one client (or ServiceAccountHarborSession) per service account / tenant process.
  3. Capability tokens are intent-scoped. A token minted for intent A must not be used with intent B, even within the same tenant.
  4. Cache JWTs only in memory scoped to that tenant and service account. Rotating the API key should be followed by constructing a new session object.
  1. Install the Kit for your language (see quickstarts).
  2. Open a ServiceAccountHarborSession (Python / TypeScript) so Harbor requests automatically attach the minted upstream JWT and correct x-tenant-id.
  3. Wire OpenAI Agents guardrails or LangGraph awrap_tool_call so tools cannot run without Harbor POST /verify succeeding.
  4. Submit evidence using sign_payee_evidence_binding (Python and native) or your server-side signer, then submit_evidence with an idempotency key when retrying.
  5. For read-only Signal access, open ServiceAccountSignalSession or construct GatewaySignalClient from the same service-account credential so tenant_id is still derived from credentials rather than caller-supplied headers.

Signal read-only dry run

For V1.0.1 release gating, a second engineer should be able to use docs only to find and exercise the tenant-bound Signal path:

  1. Start at the V1 documentation index.
  2. Find the supported route and SDK surface through Signal API reference and the SDK references.
  3. Use the documented session path to fetch the same-tenant reputation receipt, portfolio summary, explanation, and review status.
  4. Record the docs used, tenant realm, and any ambiguity that still required private guidance.

Observability

  • Python raises HarborHttpError with status_code, url, and body_text for HTTP failures.
  • TypeScript raises HarborHttpError with the same fields.
  • Gateway auth failures raise GatewayAuthError with optional status_code / body_text.

Log those fields (redact secrets) when opening partner support tickets.

Credential rotation

  1. Issue a new API key in your control plane.
  2. Construct a new ServiceAccountHarborSession / GatewayHarborTokenProvider with the new key.
  3. Drain in-flight work on the old session, then aclose / dispose.
  4. Revoke the old key in the control plane.

For drills without reissuing keys, call rotateHarborToken() or forceRotate() to mint a fresh Harbor JWT from the gateway using the same API key.

Where to go next