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