Gateway API reference

The Gateway API is Paybond's public access layer. Use it to sign users in, exchange machine credentials for short-lived access, verify protocol artifacts, manage trusted agent keys, export compliance evidence, review disputes, configure settlement and guardrail settings, and retrieve tenant-scoped Signal data.

• Transport: HTTPS. Protected routes require authenticated Paybond credentials; public verification and discovery routes are called out below.
• Tenant scope: where a route accepts x-tenant-id, it must match the authenticated tid claim. Request-body organization identifiers are treated only as hints.
• Environment scope: live/sandbox environment is derived from the authenticated credential and tenant row, never from a client-selected header. Sandbox provider behavior is simulated and does not move live money or call live provider paths.

What Gateway covers

Identity and access

Gateway signs users in, refreshes sessions, supports SSO, and exchanges machine credentials for Harbor access.

API keys use visible prefixes such as paybond_sk_live_... and paybond_sk_sandbox_.... Gateway derives the authoritative environment from storage and rejects a prefix that does not match the tenant row. Environment-less paybond_sk_<key_id>_<secret> keys are not accepted.

Protocol verification and discovery

Gateway publishes discovery documents and verification routes for delegated agent workflows, and it lets tenant admins manage the trusted agent keys those checks rely on.

Settlement configuration

Use these routes to manage the settlement settings Paybond applies for an organization. Tenant admins can update them, while read-only principals can inspect the current configuration.

Supported allowed_rails values are stripe_connect, stripe_ach_debit, and x402_usdc_base. Both Stripe rails require an active server-owned linked Stripe destination. stripe_ach_debit also requires that destination's ACH debit capability to be marked ready. x402_usdc_base requires the canonical Base receive address for the tenant environment.

Sandbox tenants use Paybond simulator destinations instead of live provider destinations. When an admin switches the console to the sandbox tenant, settlement routing can include stripe_ach_debit with the Paybond sandbox Stripe sentinel and no real Stripe test-mode key or Connect account. Live tenants remain gated on a linked Stripe destination whose ACH debit capability is marked ready.

Guardrails and audit trail

Tenant guardrail policy versions are immutable control-plane rows that configure Gateway-side policy governance. Read routes require Harbor read access; writes require tenant_admin or the tenant.admin entitlement and write a redacted audit event in the same database operation.

Gateway evaluates the active guardrail policy before forwarding Harbor policy lifecycle mutations (create draft, publish, deprecate, retire, rollback) and Harbor intent creation. In enforce mode, disallowed raw predicates, disallowed policy templates, and max intent amount violations are denied before Harbor receives the request. In observe mode, Gateway forwards the request but writes a redacted audit event with decision=observed_violation; if that audit write fails, the mutation fails closed with 503.

Rollback calls through /harbor/policy/v1/rollback require template_id, target_seq, expected_current_head_seq, expected_target_digest_hex, a human reason, and confirm: true. Gateway fetches Harbor’s current managed-policy versions before forwarding and returns 428 for missing confirmation preconditions, 400 for a missing/short reason, or 409 when the current head or target digest no longer matches. Rejected rollback attempts and confirmed rollback requests write redacted guardrail.policy_rollback audit events before any mutation is forwarded; if that pre-forward audit write is unavailable, Gateway returns 503. Gateway also writes a best-effort outcome event after Harbor responds without masking a completed upstream rollback response.

Tenant guardrail rate limits apply to guardrail_policy_mutation, policy_lifecycle_mutation, policy_sandbox_preview_test, and harbor_intent_mutation. Defaults are 20/hour for guardrail policy saves, 30/minute for policy lifecycle mutations, 120/minute for policy preview/test, and 120/minute for Harbor intent mutations. Tenants can override these groups with rate_limit_profile, keyed by route group with { "limit": <positive integer>, "window_seconds": <positive integer> }. Override values are bounded to limit <= 1000000 and window_seconds <= 86400. Existing auth, export, and webhook defaults stay route-specific, but authenticated scopes can be overridden with the existing limiter scope key such as auth_support_session, compliance_export_create, compliance_bundle_download, dispute_arbitration_export, admin_webhook_endpoint_mutation, or admin_webhook_endpoint_test; fraud-velocity limits keep their dedicated limiter.

A 429 response uses the standard Gateway JSON error envelope and includes Retry-After, RateLimit, and RateLimit-Policy headers. High-signal denials are written as redacted tenant audit events with hashed bucket keys; raw IPs, tokens, emails, DIDs, and request bodies are never stored in the abuse bucket or exported guardrail artifacts.

Sandbox simulator

Sandbox tenants can rehearse intent lifecycle and webhook flows without provider calls or live credentials. Simulator events require authenticated sandbox tenant context, derive tenant/environment/livemode fields server-side, compute a deterministic idempotency key, and write both simulated ledger and audit rows. The simulator accepts settlement_rail: "stripe_ach_debit" so tenants can exercise the ACH routing and delayed-funding UX in admin; that is separate from Paybond's optional engineering test target that calls Stripe test-mode ACH APIs with STRIPE_SECRET_KEY.

Sandbox guardrails

Sandbox guardrail routes are the Gateway-backed first-integration path documented in One-command guardrails. They require an authenticated sandbox service-account API key, derive tenant scope from the bearer credential, reject caller-supplied tenant fields (including x-tenant-id), and never accept live provider material. Gateway signs a Harbor intent, forwards create/evidence to Harbor with the derived tenant header, records matching simulator ledger/audit rows, and returns the fields Kit scaffolds expect (tenant_id, intent_id, capability_token, operation, requested_spend_cents, sandbox_lifecycle_status).

Compliance exports and ledger verification

Compliance exports package signed evidence for audits, partner reviews, and dispute handoffs. Exports can include Signal provenance, disputes, settlement records, Harbor snapshots, guardrail policy/audit JSONL artifacts, and verification artifacts. Gateway also forwards tenant-scoped Harbor continuity checks and verifier-pack workflows; it does not expose Harbor's raw paginated ledger event stream.

Dispute cases

Gateway adds organization-scoped case management around Harbor's dispute lifecycle.

Signal proxies

Gateway is also the public access layer for Signal scoring, reputation receipts, and portfolio artifacts. For the full Signal route map, see Signal API.

Harbor proxies

Gateway exposes selected Harbor routes under the /harbor prefix for teams that want one authenticated API surface for both access control and intent operations. See Harbor API for the Harbor route map and private upstream-only ledger endpoints.

Selected Harbor write routes are recognition-gated:

For /harbor/intents and /harbor/policy/v1/* lifecycle mutations, Gateway also applies the authenticated tenant's active guardrail policy before forwarding upstream. Guardrail denials return 403 guardrail_violation; audit persistence failures return 503 guardrail_audit_unavailable.

Administrative settlement operations

These routes support settlement status refreshes and webhook triage for admins and audited support users.

Tenant header validation

Routes that accept a tenant body or query parameter also accept the x-tenant-id header. When the JWT claim tid is present, the Gateway validates the header against the claim and rejects mismatches with 401 Unauthorized before any handler runs. Unauthenticated tenant identifiers in request bodies are never authoritative. Live/sandbox environment is never selected with a client-controlled header; Gateway sessions, API keys, Harbor access JWTs, Signal reads, webhooks, and settlement config derive it from the authenticated tenant credential.

Settlement routing is still resolved server-side even when clients call Harbor directly through Kit-issued tokens. Tenant admins manage the canonical config here; public Harbor calls may only request an allowed rail.

Related

• API overview
• Console sign-in
• Ledger and provenance
• V2 protocol trust
• Harbor API reference
• Signal API reference
• Errors