Partner Flow — browser redirect integration

Choose your integration path

Partner Flow entry URL

Redirect the holder to /partner/verify on the canonical host. All query parameters are required unless noted.

https://abraxasworld.xyz/partner/verify?partner_id=your-partner-id&policy_id=your-policy-v1&return_url=https%3A%2F%2Fyour-app.example.com%2Fauth%2Fabraxas%2Fcallback

Your return_url must be explicitly allowlisted in partners.allowed_return_urls. Unconfigured partners fail closed.

Lifecycle: evaluate → Passport → complete / refresh

• next=authenticate — holder must sign in
• next=passport — ID + biometric required
• next=enter — approved; redirect with receipt
• next=denied — policy denial
• next=pending_review — manual review queue

Callback query parameters (frozen — 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.

• status
• decision_id
• receipt_id
• receipt_expires_at
• credential_id
• policy_id
• partner_id

Receipt verification (server-side)

Fetch GET /api/receipts/{receipt_id}/public from your backend. No API key required. Never trust callback URL parameters alone.

• signature_valid === true — Ed25519 signature over canonical payload_hash
• decision_result === "approved" — Fail closed on denied or manual_review
• status === "active" — Reject expired, revoked, or unknown receipt state
• expires_at present, valid, and not passed — Session receipt TTL; re-verify at settlement time
• production_usable === true — Required for production gates; sandbox policies need explicit allowSandbox opt-in in your validator
• partner_id matches your integration — Prevents cross-partner receipt replay
• policy_id matches your gate — Ensures the evaluated policy is the one you requested

// Server-side only — after holder lands on your callback URL
import { validatePartnerFlowPublicReceipt } from "@/lib/partner/verifyPartnerFlowReceipt";

const receiptId = searchParams.get("receipt_id");
const res = await fetch(
  `https://abraxasworld.xyz/api/receipts/${receiptId}/public`
);
const receipt = await res.json();

const result = validatePartnerFlowPublicReceipt(receipt, {
  partnerId: "your-partner-id",
  policyId: "your-policy-v1",
  // allowSandbox: true, // only for explicit sandbox/pilot policy testing
});

if (!result.ok) {
  throw new Error(result.errors.join("; "));
}

// Grant gated action — receipt cryptographically verified

Browser session vs server API key

Browser session only (httpOnly cookie on Abraxas origin):

• POST /api/v1/partner-flow/evaluate
• POST /api/v1/partner-flow/complete
• POST /api/v1/partner-flow/refresh
• /partner/verify UI
• /passport consent and capture

Server API key (never in browser):

• POST /api/v1/verify/authorize
• GET /api/v1/verify/decisions/{id}
• POST /api/v1/verification-requests
• GET /api/v1/receipts/{id} (authenticated partner view)
• POST /api/credentials/verify

Public (no auth):

• GET /api/receipts/{receipt_id}/public
• GET /api/credentials/public-key

Webhook sandbox test delivery

Queue a single partner.webhook.test event from the partner portal with an abx_test_ key. Queued does not mean delivered — confirm in your handler and delivery history.

Sandbox test events (partner.webhook.test with test: true) are for signature and handler verification only. They are not Partner Flow lifecycle notifications such as partner.receipt.issued.

• Sandbox test event type: partner.webhook.test (test: true only)
• Lifecycle event types: partner.receipt.issued, partner.receipt.revoked, partner.access.revoked, partner.credential.revoked
• Status API: /api/partner/webhooks/status
• Delivery history: /api/v1/partner/webhooks/deliveries
• Test enqueue (sandbox key + webhooks:read, user-initiated only): /api/partner/webhooks/test-delivery
• A successful enqueue returns queued: true. Delivery is asynchronous; inspect delivery history for delivered, retrying, or failed outcomes.
• Webhook endpoint URL and signing secret are configured by Abraxas ops — not self-serve.

External design partner sandbox

Two independent tracks: Partner Flow (browser redirect + public receipt verification) and Webhooks (optional, requires webhooks:read). Complete each track on its own — they do not share credentials or proof.

Sandbox receipts with production_usable: false cannot authorize Production access. Reserve currently_valid === true for Production gates only.

Track A — Partner Flow

• Operator provisioning: Abraxas ops supplies partner_id, policy_id, and an allowlisted return_url. You cannot self-build a complete entry URL without all three.
• Partner Flow entry URL: Redirect holders to /partner/verify with operator-supplied policy_id and return_url. Use the template below — do not guess missing values.
• Callback handler: Your server receives frozen callback query parameters (no PII) and fetches GET /api/receipts/{receipt_id}/public before granting access.
• Sandbox receipt validated: Confirm signature_valid, matching partner_id/policy_id, and approved decision. production_usable: false is expected — sandbox receipts never authorize Production access.

Abraxas operations supplies policy_id and return_url. Replace the placeholders below before redirecting holders.

https://abraxasworld.xyz/partner/verify?partner_id=your-partner-id&policy_id=%3Cpolicy_id%3E&return_url=%3Chttps%3A%2F%2Fyour-app.example.com%2Fauth%2Fabraxas%2Fcallback%3E

Sandbox receipt checks

• signature_valid === true — Ed25519 signature over canonical payload_hash — required even in sandbox
• decision_result === "approved" — Fail closed on denied or manual_review outcomes
• partner_id matches your integration — Prevents cross-partner receipt replay
• policy_id matches your gate — Ensures the evaluated policy is the one Abraxas ops provisioned
• production_usable may be false — Expected for sandbox policies — do not use sandbox receipts to gate Production access
• currently_valid may be false — Sandbox receipts often invalidate with production_not_usable:false — this is expected, not a failure

Track B — Webhooks (optional)

partner.webhook.test events are webhook transport tests only. They are never validated via GET /api/receipts/{receipt_id}/public.

• webhooks:read scope: Default promote keys include verify:credential and verify:registry only. Request a separate key with webhooks:read from Abraxas ops for this track.
• Endpoint registered: Abraxas ops registers your HTTPS callback and enables delivery after you confirm signature handling.
• Test event queued: User-initiated POST enqueues a single partner.webhook.test event. Queued does not mean delivered.
• HTTP delivered: Delivery history shows status delivered — your endpoint returned a successful HTTP response. This is transport only, not signature verification.
• Signature verified by your receiver: Manually confirm your handler validated the Abraxas webhook signature. Abraxas cannot infer this from delivery records.

Default promote keys include verify:credential and verify:registry only. Request webhooks:read via Abraxas ops for webhook testing.

Approved design partners: your Abraxas operator shares the full 14-day external pilot playbook during secure sandbox handoff. Use this section plus /design-partner while you wait. Production activation is a separate later step.

Errors and status behavior

Copy-paste redirect

// Server-render or link — never embed API keys in the browser
const verifyUrl = "https://abraxasworld.xyz/partner/verify?partner_id=your-partner-id&policy_id=your-policy-v1&return_url=https%3A%2F%2Fyour-app.example.com%2Fauth%2Fabraxas%2Fcallback";

// <a href={verifyUrl}>Continue with Abraxas</a>

One verification. Faster onboarding. Fewer forms.

Abraxas helps users prove eligibility and securely continue into partner experiences without repeatedly exposing sensitive identity information.

Operator provisioning

Partner rows, policies, callback allowlists, and sandbox credentials are provisioned by Abraxas operators after manual review. Approved partners then use the Partner Portal to validate their assigned integration. There is no self-serve Production provisioning or automatic API-key issuance.