Entropy API

Endpoint

POST/v1/entropy

Request

{
  "format": "hex",
  "length": 32,
  "size_bytes": 32,
  "request_id": "optional-trace-id"
}

Headers

Authorization: Bearer qsg_live_… — API key issued at provisioning
Content-Type: application/json

Response (200)

{
  "success": true,
  "request_id": "uuid-v4-string",
  "timestamp": "2026-09-02T12:00:00.000Z",
  "issued_at": "2026-09-02T12:00:00.000Z",
  "data": {
    "format": "hex",
    "length": 32,
    "size_bytes": 32,
    "entropy": "a1b2c3d4...",
    "encoding": "hex"
  },
  "provenance": {
    "source_class": "hardware-derived",
    "source_id": "batch-2026-06-10-001",
    "backend_class": "validated-hardware-source",
    "entropy_score": 0.9946,
    "conditioning": "HKDF-SHA-256",
    "unique_states": 8192,
    "job_epoch": "2026-06-10",
    "health_check": {
      "rct_passed": true,
      "apt_passed": true,
      "timestamp": "2026-09-02T11:59:58.000Z"
    }
  },
  "fallback": {
    "is_fallback": false,
    "reason": null,
    "original_source": null
  },
  "audit": {
    "reservoir_remaining_bits": 912635
  },
  "tier": "standard",
  "rate_limit": {
    "remaining": 98,
    "reset_at": 1788624000000
  },
  "billing": {
    "tier": "standard",
    "units": 32,
    "weight": 1.0,
    "charged_units": 32,
    "unit_definition": "bytes"
  }
}

Status codes

200Success. Body contains entropy bytes, provenance, and audit metadata. 401Unauthorized. Missing or invalid API key. 402Quota exceeded. Included draws consumed; overage billing applies on next request if subscription active. 405Method not allowed. Only POST is accepted. 400Invalid request body. Body must be valid JSON. 429Rate limit exceeded. Retry after the value in Retry-After. 503Service degraded. Fallback path engaged; body still issued with fallback.is_fallback: true and fallback.reason populated.

Encrypted Draw

POST /v1/entropy/encrypted performs a hybrid key encapsulation (X25519 + ML-KEM-1024) and returns entropy encrypted to the caller's public key. Private beta — enrollment is invite-only and requires a Verified, Verified+, or Enterprise tier key. Contact us to join.

POST/v1/entropy/encrypted

Request

{
    "format": "base64",
    "length": 32,
    "suite": "QSG-HYBRID-1",
    "client_public_keys": {
      "x25519": "<base64url 32 bytes>",
      "ml_kem_1024": "<base64url 1568 bytes>"
    },
    "client_nonce": "<base64url >= 16 bytes>",
    "key_id": "my-key-001"
  }

Response (200)

{
    "success": true,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-09-02T12:00:00.000Z",
    "suite": "QSG-HYBRID-1",
    "kem": {
      "x25519_ephemeral_pk": "base64url — 32 bytes",
      "mlkem1024_ciphertext": "base64url — 1568 bytes"
    },
    "ciphertext": "base64url — AES-256-GCM ciphertext",
    "nonce": "base64url — 12-byte nonce",
    "tag": "base64url — 16-byte GCM tag",
    "aad_hash": "base64url — SHA-256 of canonical AAD (see protocol doc)",
    "expires_at": "2026-09-02T12:05:00.000Z",
    "format": "base64",
    "length": 32,
    "provenance": {
      "source_class": "hardware-derived",
      "source_id": "batch-2026-06-10-001",
      "entropy_score": 0.9946,
      "conditioning": "HKDF-SHA-256"
    },
    "rate_limit": {
      "remaining": 499,
      "reset_at": 1756902000000
    }
  }

Status codes

200Success. kem, ciphertext, nonce, and tag returned. 401Unauthorized. 402Quota exceeded. 403Tier not authorized. Encrypted draws require Verified tier or higher. 400Validation error. Missing or malformed client_public_keys or client_nonce, unsupported suite, or invalid format/length. Codes: invalid_key_material, unsupported_suite, invalid_length. 503Beta not enabled. QSG Encrypt is in private beta — contact us to join. 429Rate limit exceeded.

Field Reference

format (string, request) — "hex" | "base64" | "raw". Defaults to "hex".
length (int, request) — Number of bytes to draw. Range: 1–4096. Defaults to 32.
size_bytes (int, request) — Alias for length. Accepted for API portability.
request_id (string, request) — Optional client-provided trace ID. Max 64 chars.
success (boolean) — Whether the request succeeded.
request_id (string) — Server-assigned unique identifier for this request.
data.format / data.length / data.size_bytes / data.entropy / data.encoding — The returned entropy in the requested format.
provenance.source_class (enum) — "hardware-derived" | "csprng-fallback". Critical field.
provenance.entropy_score (float) — Quality score, 0.0–1.0. Threshold ≥ 0.99.
provenance.conditioning (string) — Cryptographic conditioning applied, e.g. "HKDF-SHA-256".
provenance.health_check (object) — NIST SP 800-90B RCT and APT results.
fallback.is_fallback (boolean) — false on normal draw; true with fallback.reason on fallback.
audit.reservoir_remaining_bits — Pool capacity at time of draw.
tier (string) — Echo of the authenticated tier.
rate_limit.remaining / rate_limit.reset_at — Current window capacity.
billing (object, Builder+) — units, weight, charged_units. Omitted for Public tier.
timestamp / issued_at (string) — ISO 8601 timestamp of the response.

Fallback Reasons

When fallback.is_fallback is true, the fallback.reason field carries one of these codes.

reservoir_depletedHardware pool exhausted. Draw re-issued from CSPRNG. quality_threshold_not_metCandidate batch scored < 0.99 on min-entropy. Re-issued from CSPRNG. entropy_service_unavailableInternal entropy service unreachable. CSPRNG fallback engaged. maintenance_modeService in maintenance. CSPRNG fallback engaged.

Quality Assurance

Raw measurement output is cryptographically conditioned before admission. Per-batch min-entropy is estimated; only batches scoring ≥ 0.99 are admitted to the reservoir.

NIST SP 800-90B Repetition Count Test (RCT) and Adaptive Proportion Test (APT) are run on a rolling 1024-byte sample. Failed tests force CSPRNG fallback regardless of entropy_score.

Pool byte-age cap: 14 days. Reservoir must hold at least 1 MB before a hardware-derived draw is admitted. Maximum consumption per draw: 90%.

For the full architectural breakdown, see Service Architecture.

Rate Limits

Per-API-key rolling-window limits. Burst capacity up to 2× for 5 seconds. Higher tiers available on request.

Tier	Requests / Minute	Max Length
Public	10	4,096 bytes
Builder	100	4,096 bytes
Standard	100	4,096 bytes
Standard+	200	4,096 bytes
Verified	250	16,384 bytes
Verified+	500	16,384 bytes
Enterprise	1,000	16,384 bytes

Get a sandbox key

Standard tier; full response shape; audit chain attached.

Request Access Developer Guide