Partner Flow OpenAPI contract

Auth boundaries

• Browser entry & session — holder on abraxasworld.xyz; `abraxas_browser_session` cookie; no partner API key in client code.
• Passport handoff — same browser session during first-time ID verification (`next=passport`).
• Public receipt — partner backend fetches `GET /api/receipts/{receiptId}/public` (no auth, CORS enabled).
• Server-to-server API-key routes are intentionally excluded from this contract (see below).

Documented operations

Browser entry & session

• GET /partner/verify — Browser redirect entry — holder starts Partner Flow
• POST /api/v1/partner-flow/evaluate — Evaluate holder credential against partner policy (browser session)
• POST /api/v1/partner-flow/complete — Complete flow after manual approval and issue session receipt
• POST /api/v1/partner-flow/refresh — Re-issue session receipt when prior receipt expired but credential remains valid

Passport & consent handoff

• GET /passport — Passport UI — ID capture and consent after evaluate returns next=passport
• GET /api/v1/verification-requests/{verificationRequestId} — Holder preview of verification request before consent
• POST /api/v1/verification-requests/{verificationRequestId}/consent — Holder consents; policy engine returns decision
• POST /api/v1/verification-requests/{verificationRequestId}/decline — Holder declines verification request

Public receipt verification

• GET /api/receipts/{receiptId}/public — Public eligibility decision receipt (no auth, no PII)

Callback parameters (no PII)

Callback query parameters contain no PII — no legal name, DOB, document numbers, images, or wallet address. Verify eligibility via the signed receipt, not the URL alone.

Receipt verification (fail closed)

• signature_valid: must be true
• decision_result: must be "approved"
• status: must be "active" (missing fails)
• expires_at: required, valid ISO-8601, not expired at verification time
• production_usable: must be true unless allowSandbox opt-in
• partner_id: must match expected partner integration id
• policy_id: must match expected policy gate id

Sandbox policies: set explicit allowSandbox: true only for pilot testing — never in production gates.

Example — fetch public receipt (curl)

curl -sS "https://abraxasworld.xyz/api/receipts/RECEIPT_ID/public" \
  -H "Accept: application/json"

Example — verify receipt (JavaScript, server-side)

// Server-side — verify after holder callback redirect
const receiptId = new URL(request.url).searchParams.get("receipt_id");
const res = await fetch(
  "https://abraxasworld.xyz/api/receipts/" + encodeURIComponent(receiptId) + "/public",
  { headers: { Accept: "application/json" } },
);
if (!res.ok) throw new Error("Receipt fetch failed: " + res.status);
const receipt = await res.json();

// Fail closed — see lib/partner/verifyPartnerFlowReceipt.ts
if (receipt.signature_valid !== true) throw new Error("signature_invalid");
if (receipt.decision_result !== "approved") throw new Error("decision_not_approved");
if (receipt.status !== "active") throw new Error("status_not_active");
if (!receipt.expires_at || new Date(receipt.expires_at) <= new Date()) {
  throw new Error("receipt_expired");
}
if (receipt.production_usable !== true) throw new Error("production_not_usable");
if (receipt.partner_id !== "your-partner-id") throw new Error("partner_mismatch");
if (receipt.policy_id !== "your-policy-v1") throw new Error("policy_mismatch");

Intentionally excluded (private / other integration paths)

• POST /api/v1/verification-requests — Server-to-server integration — requires partner API key (verify:requests); see /docs/partner-verification-requests
• GET /api/v1/receipts/{receiptId} — Partner-authenticated receipt view — requires API key; browser Partner Flow uses GET /api/receipts/{receiptId}/public
• GET /api/v1/decision-receipts/{receiptId}/status — Partner-authenticated receipt status — requires API key
• POST /api/credentials/verify — Credential/registry verify path — separate integration; see /docs/relying-party-verify
• POST /api/v1/authorize — Abraxas Connect path — separate integration; see /docs/ail