API Overview

Documentation

An overview of QUORUM's integration surface. QUORUM runs inside each institution's environment, so the base URL is the institution's own deployment. The full OpenAPI description (api-v1.yaml) and integration guide are provided during onboarding.

Authentication

Every institutional request carries two headers. The key is checked with a constant-time comparison after the organization is looked up, and every route is scoped to that organization. A request whose body names a different organization is rejected.

HTTP HEADERS
x-api-key: ••••••••••••••••
x-org-id: ••••••••

Message-queue requests are authenticated with an HMAC-SHA256 over the correlation ID and body using the organization's API key, or by binding a broker to one organization.

Browser SDK

The JavaScript SDK collects behavioural and device signals and returns them as a header to attach to your own requests. Raw keystroke and pointer streams are reduced to derived values in the browser.

<script src="/quorum-sdk.js"></script>
<script>
  const quorum = new QuorumSDK({ userId: 'usr_abc123' });
  await quorum.init();
  const headers = quorum.getHeaders();   // { 'X-Quorum-CIV-Signals': ... }
</script>

Signals include canvas and WebGL hashes, audio-context entropy, hardware profile, typing speed and variance, pointer entropy, accelerometer and touch-pressure characteristics, and frame-timing jitter. There are no Python or Java SDKs.

Decision Endpoints

Endpoint	Purpose
POST /api/v1/analyze	Score a session: behavioural signals, plus the rule engine when transaction facts are supplied (60% / 40%).
POST /api/v1/op-tx	Screen and record a transaction. ISOLATED is rejected (403); ELEVATED_RISK is recorded as flagged.
POST /api/iso8583/authorize	Raw ISO 8583 in, raw ISO 8583 out (binary or hex; ?framing=length for 2-byte length prefixes).
Kafka / AMQP	Signed messages in, verdict replies out.
Flat-file watcher	One verdict, or an ERROR line, per input line.

POST /api/v1/analyze
{
  "target":  { "type": "session", "session_id": "s-1029", "user_id": "u-77" },
  "signals": { "typing_speed": 94, "typing_variance": 0.21, "is_headless": false },
  "transaction": { "amount": 820, "crossBorder": true, "cardPresent": false }
}

Only the facts you supply are evaluated. Omitted facts are treated as absent, never defaulted.

Response

{
  "decisionId": "3f6c…a91e",
  "verdict":    "ELEVATED_RISK",
  "riskScore":  52.4,
  "confidence": 75,
  "flags":      ["CROSS_BORDER", "NEW_DEVICE"],
  "reasoning":  "…",
  "sessionId":  "s-1029",
  "tiers": {
    "behavioral": { "score": 47.0, "flags": [ … ] },
    "fraud":      { "score": 60,   "flags": [ … ], "evaluated": true }
  }
}

The decision is recorded before the response is sent. Use decisionId to request a decision proof later.

Verdicts

Verdict	Score	Notes
VERIFIED	< 15	—
AUTHORIZED	15–39	—
ELEVATED_RISK	40–69	Recorded as flagged on the transaction channel
ISOLATED	≥ 70	Rejected on the transaction channel; signed counterfactual certificate issued

High-risk blocks can open a draft SAR/STR case for the institution to complete. A second person must approve it, and nothing is filed automatically.

Flags

Flags name the signals and rules that contributed to a verdict: behavioural flags from the scoring tier, and the tags of fired rules from the institution's own rule set. Because rules are defined per institution, the flag list is specific to each deployment and is documented during onboarding.

Evidence and Institutional Endpoints

Endpoint	Purpose
GET /api/institutional/v1/audit/decision-proof/{id}	Proof that a decision is in the signed ledger
GET /api/institutional/v1/audit/inclusion-proof/{logId}	Merkle inclusion proof for a ledger entry
GET /api/institutional/v1/audit/signing-keys	Public keys for offline verification
POST /api/institutional/v1/compliance/zk/decision-score	Zero-knowledge proof that a score was within bounds
/api/institutional/v1/sar-profile, /sar-filings/…	SAR/STR preparation, dual approval and acknowledgement
/api/institutional/v1/he/…	Encrypted scoring (Microsoft SEAL)
POST /api/institutional/v1/attestation/verify	Verify AMD SEV-SNP / Intel TDX evidence
/api/v1/federation/…, /api/v1/sanctions-psi/…	Federation pseudonyms and private sanctions screening
/api/security/v1/block-ip, /unblock-ip	Per-organization IP blocks, written to the ledger

Errors

Status	Meaning
400	Invalid request
401	Missing or invalid credentials
403	Organization mismatch, or a transaction blocked with verdict ISOLATED
429	Rate limit exceeded
503	Rules could not be evaluated or the decision could not be recorded — no verdict issued

Webhooks

QUORUM can POST event notifications to an HTTPS endpoint registered by the institution. Each delivery carries an X-Quorum-Signature header — an HMAC of the body with the webhook's secret — plus X-Quorum-Event and X-Quorum-Delivery. Deliveries to internal or unsafe addresses are refused, and failed deliveries are retried with backoff.

Rate Limits

A global limiter applies to all API requests before tenant resolution, and individual routes carry their own limits (for example 60 requests per minute on the analyze route). Organization-specific limits are configured per deployment. Exceeding a limit returns HTTP 429.