Gateway API reference
The Paybond Gateway (go/gateway) is the single public entry point to Paybond. It authenticates sessions, scopes every call to a tenant realm, and proxies Harbor and Signal endpoints with tightened RBAC.
- Normative implementation:
go/gateway/internal/httpserver. - Transport: HTTPS; session Bearer JWT required on protected routes.
x-tenant-idmust match the JWTtidon routes that accept it.
Route map
Control plane
| Method | Path | Description |
|---|---|---|
POST | /v1/auth/login | Email and password (or magic-link hand-off) session login. Sets session cookie and returns a Bearer JWT. |
POST | /v1/auth/refresh | Rotates the session token. |
POST | /v1/auth/logout | Revokes the session cookie and Bearer pair. |
GET | /v1/auth/principal | Returns the authenticated principal (tenant, roles, entitlements). |
POST | /v1/auth/harbor-access | Mints a short-lived Harbor access JWT from a service-account API key. Used by the Paybond Kit (ServiceAccountHarborSession.open). |
GET | /v1/auth/sso/initiate | Start a tenant SSO flow. Redirects to the configured OIDC or SAML IdP. Rate-limited per client IP. |
GET | /v1/auth/sso/callback | OIDC callback handler. Verifies IdP response, provisions membership if allowed, returns a Paybond access token. Rate-limited per client IP. |
POST | /v1/auth/sso/callback | SAML ACS endpoint. Verifies signed SAML response/assertion, provisions membership if allowed, returns a Paybond access token. Rate-limited per client IP. |
POST | /v1/auth/support-session | Issues a time-boxed support session with audited RBAC. |
Compliance audit exports (V1-009)
Tenant-scoped ZIP bundles with a signed manifest.json for Signal provenance, disputes, Stripe settlements, Harbor intent snapshots, and proof artifacts (proof/ledger_verifier_pack.json, proof/verifier_pack.json, and signal/portfolio_artifact.json when Signal proof material is included). Full OpenAPI: gateway-audit-export-openapi.yaml.
| Method | Path | Description |
|---|---|---|
POST | /v1/compliance/audit-exports | Create a bundle job. Returns metadata plus a short-lived download JWT (aud = paybond-audit-export-download). |
GET | /v1/compliance/audit-exports | List jobs for the authenticated tenant. |
GET | /v1/compliance/audit-exports/{job_id} | Job status; pass ?issue_download=1 to mint a fresh download JWT. |
POST | /v1/compliance/audit-exports/{job_id}/verify | Re-verify the persisted ZIP, signed manifest, and listed artifact digests for one tenant-scoped export job. |
DELETE | /v1/compliance/audit-exports/{job_id} | Revoke the job and remove the bundle file (requires tenant_admin or audited support session). |
GET | /v1/compliance/audit-exports/{job_id}/bundle?token=… | Download the ZIP stream (download JWT only; not the session token). |
GET | /v1/compliance/ledger/verify | Trigger a tenant-scoped Harbor ledger continuity check through the gateway and return explicit pass/fail guidance. |
GET | /v1/compliance/ledger/verifier-pack | Download the current tenant-scoped Harbor verifier pack through the gateway. Useful for offline append-only revalidation. |
POST | /v1/compliance/ledger/verifier-pack/verify | Re-verify an exported ledger verifier pack without direct Harbor sled access. |
See also the operational runbook: docs/operations/audit-export-compliance.md.
Dispute cases
Wraps Harbor's dispute lifecycle with tenant-scoped case rows in Postgres.
| Method | Path | Description |
|---|---|---|
POST | /v1/disputes/cases | Create a dispute case. |
POST | /v1/disputes/cases/link-disputed-intent | Link an already-open Harbor dispute to a case row. |
GET | /v1/disputes/cases | List cases (status, intent_id, limit, offset). |
GET | /v1/disputes/cases/{case_id} | Case detail with evidence refs and notes. |
POST | /v1/disputes/cases/{case_id}/resolve | Resolve with outcome and rationale. |
POST | /v1/disputes/cases/{case_id}/assign | Assign ownership within the tenant. |
POST | /v1/disputes/cases/{case_id}/evidence | Attach evidence reference. |
POST | /v1/disputes/cases/{case_id}/notes | Append a dispute note. |
GET | /v1/disputes/cases/{case_id}/export/arbitration | Rate-limited signed arbitration package. |
Signal proxies
The Gateway is the public home for Signal scoring, reputation receipts, and portfolio artifacts. Contracts are documented in Signal API; the Gateway enforces signal.read RBAC and tenant scope before forwarding to the indexer.
| Method | Path | Description |
|---|---|---|
GET | /reputation/{operator_did} | Signed operator receipt (optionally ?score_version=). |
GET | /signal/v1/overview | Portfolio rollups and current scores. |
GET | /signal/v1/review-queue | Tenant-scoped review queue for low-support or anomalous operators. |
GET | /signal/v1/operators/{operator_did}/trend | Append-only score snapshots. |
GET | /signal/v1/operators/{operator_did}/explanation | Signed “why did this move?” delta plus confidence metadata. |
GET | /signal/v1/operators/{operator_did}/review-status | Explicit review state, maturity tier, annotations, and friction metadata. |
POST | /signal/v1/operators/{operator_did}/review-events | Authenticated review-open, appeal, or replay workflow request. |
GET | /signal/v1/operators/{operator_did}/score-model-versions | Historical score_version rows preserved per operator. |
GET | /signal/v1/portfolio/summary | Tenant-wide aggregates. |
GET | /signal/v1/portfolio/signed-export | Signed portfolio artifact. |
GET | /audit | Tenant-scoped Signal provenance events (?operator_did=&limit=&offset=). |
Harbor proxies
The Gateway reverses-proxies Harbor under the /harbor prefix with tightened RBAC. See Harbor API for the route map; the public paths are the upstream paths prefixed with /harbor.
Stripe operational surfaces
Administrative endpoints used by the console during settlement reconciliation. RBAC: tenant_admin or audited support.
| Method | Path | Description |
|---|---|---|
POST | internal /v1/stripe/reconcile | Trigger one reconciliation pass. |
GET | internal /v1/stripe/webhook-health | Recent webhook delivery and replay health. |
GET | internal /v1/stripe/webhook-failures | Failed webhook rows for triage. |
Tenant header contract
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.