Documentation

Everything you need to integrate QSG entropy into your stack. Service is delivered at api.quantumsecuregateway.com.

Quickstart

  1. 1. Get a key

    Request access at /auth/request-access. A sandbox key is provisioned in 24-48 hours.

  2. 2. Configure your Worker

    Add the QSG API base to your wrangler.toml:

    [vars]
QSG_API_URL = "https://api.quantumsecuregateway.com"
QSG_API_KEY = "<your-key>"

  3. 3. Make your first request

    curl -X POST https://api.quantumsecuregateway.com/v1/entropy \
  -H "Authorization: Bearer $QSG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size_bytes":32,"format":"hex"}'

  4. 4. Verify provenance

    Each response includes a provenance.source_id. POST it to /v1/verify with the request_id to retrieve the signed record and validation status. Verification requires Verified, Verified+, or Enterprise tier.

API Reference

POST/v1/entropy

Draw entropy. Returns hex / base64 / binary output plus provenance metadata.

POST/v1/verify

Validate a previous entropy draw. Body: {"request_id": "<id>"}. Returns verification.status (verified | validation_failed) plus full health_tests and validation_errors. Requires Verified tier or higher.

GET/v1/audit/:provenance_id

Audit trail export. Returns the full audit chain segment around a draw, signed and JSONL-formatted for replay. Requires Verified tier or higher.

GET/v1/status

Public service-status snapshot. Returns pool remaining_bytes, entropy_score, source_class, billing.schema_version, the active tier roster, and the endpoint inventory. No authentication required.

GET/health

Liveness probe. Returns 200 when the edge and reservoir are healthy.

Provenance Schema

Every draw returns a provenance record with the following fields. Full schema is published in the Compliance Pack.

{
  "request_id": "01J...",
  "timestamp": "2026-06-24T14:33:12Z",
  "data": {
    "format": "hex",
    "length": 32,
    "size_bytes": 32,
    "entropy": "<hex output>",
    "encoding": "hex"
  },
  "key_exchange": "X25519+ML-KEM-1024",
  "provenance": {
    "source_id": "ibm-quantum-01",
    "source_class": "hardware-derived-premium",
    "entropy_score": 0.9972,
    "conditioning": "HKDF-SHA3-256",
    "health_check": {
      "rct_passed": true,
      "apt_passed": true,
      "timestamp": "2026-06-24T14:33:12Z"
    }
  },
  "fallback": {
    "is_fallback": false,
    "reason": null,
    "original_source": null
  },
  "audit": {
    "reservoir_remaining_bits": 41838208
  },
  "tier": "standard",
  "rate_limit": {
    "remaining": 998,
    "reset_at": "2026-06-24T14:34:12Z"
  }
}

Verify Response Shape

Returned by POST /v1/verify. verification.status is verified only when all health tests pass and entropy_score is at or above the 0.99 admission threshold. validation_errors is an array of human-readable failure reasons on rejection, null on success.

{
  "success": true,
  "verification": {
    "status": "verified",
    "request_id": "01J...",
    "timestamp": "2026-06-24T14:33:12Z",
    "provenance_valid": true,
    "entropy_score": 0.9972,
    "source_class": "hardware-derived-premium",
    "conditioning": "HKDF-SHA3-256",
    "health_tests": {
      "rct_passed": true,
      "apt_passed": true,
      "timestamp": "2026-06-24T14:33:12Z"
    },
    "validation_errors": null,
    "verified_at": "2026-06-24T14:35:01Z"
  },
  "requestId": "01J..."
}

Billing Model

Weight brackets

Per-draw billing weight scales with bytes drawn and source class. Hardware draws at 1.0×, conditioned at 0.5×, fallback at 0.25×. See Tiers for unit pricing.

Rate limits

Per-key rate limits scale with tier. Builder: 100 req/min. Standard / Standard+: 1,000 req/min. Verified / Verified+: 5,000 req/min. Enterprise: custom. Burst headroom per tier.

SDKs

TypeScript / JavaScript

Cloudflare Workers, Node, browser. Coming soon.

Python

3.10+. Coming soon.

Go

1.22+. Coming soon.

Ready to integrate?

Get a sandbox key and start drawing entropy in minutes.

Request Access