PureRand Quantum Choice Engine — API

Base URL: https://api.purerand.com/qr

PureRand provides verifiable randomness for decisions, sampling, digit strings, and crypto-grade key material. Each successful call returns a hash and a verify_url.

Highlights

Choices (YES/NO, CSV list, 0..N-1) and digit strings (length/base).
Unique picks without replacement (/multi).
Crypto material via ?kind=crypto (nonces, salts, seeds, tokens).
2-step challenge with HMAC for high-value outputs (/random/{len}/{type}).
Verification via /verify.

What you get back

result hash verify_url timestamp

This documentation includes a privacy-safe request log format and a shareable “Support bundle”. It intentionally omits internal schemas, secrets, and raw entropy samples.

Security & Hardening

Registration & activation

New accounts start inactive. They become active after email verification via GET /activate/{token}.
Portal endpoints are protected by session cookies + CSRF tokens.
API endpoints use Bearer auth (Authorization header).

Operational guidance

Never send API keys / secret keys in URLs, referrers, or client-side analytics.
For debugging, use the request log (/requests) or a redacted support bundle.
Implement backoff and retry behavior for 429 and transient network errors.

Authentication

API endpoints use Bearer authentication. Send your API key in the Authorization header:

Header Bearer token

Authorization: Bearer YOUR_API_KEY

Portal endpoints

/register, /activate/{token}, /login, /logout, /keys use a browser session + CSRF token.
/rotate_key uses HMAC proof with the current secret (see endpoint section).

Quick Start

cURL — YES/NO (root endpoint)

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.purerand.com/qr/?n=YES,NO"

cURL — Crypto material

Example: generate a 32-byte urlsafe token (treat it as secret).

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.purerand.com/qr/?kind=crypto&type=api_key&format=urlsafe"

2-Step Challenge — flow outline

# STEP 1: request challenge (returns 401 + JSON)
curl -s -i \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.purerand.com/qr/random/1024/bits"

# STEP 2: call again with request_id, timestamp, signature, challenge_token
# signature = HMAC_SHA256_HEX(data_to_sign, secret_key)

Endpoints

GET `/` — Root: choices & numbers

Query:

n — CSV list or integer N ⇒ picks 0..N-1
length + base (2..36) ⇒ random digit string
kind=crypto ⇒ crypto material mode (see below)

Examples:

GET https://api.purerand.com/qr/?n=YES,NO
GET https://api.purerand.com/qr/?n=5
GET https://api.purerand.com/qr/?length=16&base=16

GET `/` — Crypto material (`kind=crypto`)

Query:

kind=crypto (required)
type (required) — supported: api_key, hmac_seed, asym_seed, wallet_seed, signing_seed, tls_seed, session_key, session_id, token_seed, nonce, salt, challenge, zk_seed, zk_nonce, jitter_seed, container_id
bytes (optional) — 4..64 overrides defaults
format (optional) — hex | base64 | urlsafe (default)

Crypto outputs are sensitive. Never expose them publicly. Use the request log/support bundle for debugging, not raw secrets.

GET `/random/{length}/{type}` — Stateless 2-step challenge

Types: bits | integer | float.

GET https://api.purerand.com/qr/random/1024/bits
# 401 JSON: {challenge_token, request_id, timestamp, data_to_sign}

GET https://api.purerand.com/qr/random/1024/bits?request_id=...&timestamp=...&signature=...&challenge_token=...
# 200 JSON: {random_data, hash, verify_url, ...}

GET `/multi` — Unique picks (no replacement)

GET https://api.purerand.com/qr/multi?values=1,2,3,4,5&count=3
GET https://api.purerand.com/qr/multi?min=0&max=19&count=3

GET `/verify?hash=...` — Verify block

GET https://api.purerand.com/qr/verify?hash=BLOCK_HASH

GET `/ledger` — Chain browsing

Intended for inspection/debug. Depending on deployment policy it may be restricted and/or redacted.

GET `/metrics` — Service metrics

High-level indicators only. No raw entropy samples are exposed.

GET `/requests` — Request log (your own history)

Returns a privacy-safe history of your calls. Designed for debugging and audits. Omits API keys, secret keys, fingerprints, and raw entropy samples.

Query:

start / end (optional) — YYYY-MM-DD or ISO-like
limit (optional) — max 500

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.purerand.com/qr/requests?start=2025-12-01&end=2025-12-13&limit=3"

# => {
#   "items":[
#     {
#       "id": 12345,
#       "ts": "2025-12-13T11:44:12Z",
#       "route": "crypto",
#       "params": {"type":"nonce","bytes":12,"format":"urlsafe"},
#       "result": {"value":"(redacted)","type":"nonce"},
#       "verify_url": "/qr/verify?hash=6f1c...a9b2"
#     },
#     {
#       "id": 12344,
#       "ts": "2025-12-13T11:40:02Z",
#       "route": "multi",
#       "params": {"count":3,"values":[1,2,3,4,5]},
#       "result": {"selected":[2,5,1]},
#       "verify_url": "/qr/verify?hash=91aa...03ff"
#     }
#   ]
# }

POST `/register`

Creates an account and sends an activation email (account is inactive until verified).

POST https://api.purerand.com/qr/register
{ "username": "alice", "email": "alice@example.com", "password": "********", "csrf_token": "..." }

GET `/activate/{token}`

Activates an account via email verification token.

GET https://api.purerand.com/qr/activate/ACTIVATION_TOKEN_64_CHAR

POST `/login`

Starts portal session (requires active account + CSRF).

POST https://api.purerand.com/qr/login
{ "username": "alice", "password": "********", "csrf_token": "..." }

GET `/keys`

Return latest api_key + secret_key for the logged-in user.

GET `/csrf`

Fetch CSRF token for portal requests.

POST `/rotate_key`

Rotate key material with HMAC proof. (Keep secret_key private.)

POST https://api.purerand.com/qr/rotate_key
{
  "api_key": "CURRENT_API",
  "ts": 1730712345,
  "signature": "HMAC_SHA256_HEX('rotate|'+api_key+'|'+ts)",
  "grace_seconds": 86400,
  "revoke_old_now": false
}

GET `/me`

Portal session status (example: {"logged_in":true,"user":"alice"}).

POST `/logout`

End portal session (requires CSRF).

POST https://api.purerand.com/qr/logout
{ "csrf_token": "..." }

2-Step Challenge — Details

Step 1: Request /random/{len}/{type}. Server returns a challenge payload.
Step 2: Compute signature = HMAC_SHA256(data_to_sign, secret_key) and call again with the provided fields.

Message to sign:

{length}|{type}|{request_id}|{timestamp_utc}

Request Log

The endpoint /requests returns a safe-to-share history of your own calls: timestamps, logical route, normalized parameters, result summary, and verification URL.

Fields

id — block id
ts — UTC timestamp
route — logical operation (yesno/choice/number/multi/crypto/bits/integer/float)
params — request parameters (safe)
result — returned data; crypto values may be redacted
verify_url — integrity verification reference

Support bundle (safe to share)

For support/debugging you can share a redacted request history: it includes timestamps, routes, parameters and verification URLs, but removes sensitive values.

Example shareable JSON

{
  "service": "PureRand Quantum API",
  "base_url": "https://api.purerand.com/qr",
  "generated_at_utc": "2025-12-13T12:34:56Z",
  "notes": "This bundle is redacted: no API keys, no secret keys, no crypto output values.",
  "items": [
    {
      "id": 12345,
      "ts": "2025-12-13T11:44:12Z",
      "route": "crypto",
      "params": {"type":"nonce","bytes":12,"format":"urlsafe"},
      "result": {"value":"(redacted)","type":"nonce"},
      "verify_url": "/qr/verify?hash=6f1c...a9b2"
    },
    {
      "id": 12344,
      "ts": "2025-12-13T11:40:02Z",
      "route": "multi",
      "params": {"count":3,"values":[1,2,3,4,5]},
      "result": {"selected":[2,5,1]},
      "verify_url": "/qr/verify?hash=91aa...03ff"
    },
    {
      "id": 12343,
      "ts": "2025-12-13T11:39:30Z",
      "route": "yesno",
      "params": {},
      "result": {"selected":"YES"},
      "verify_url": "/qr/verify?hash=0c0d...9e2a"
    }
  ]
}

Redaction rules

Always redact any crypto output value (nonce/salt/seed/api_key material).
Never include API keys, secret keys, signatures, request IDs, internal fingerprints, or raw entropy samples.
Keep verify_url so integrity can be validated without exposing secrets.

Privacy & Data Exposure

What is shown

Functional parameters and results needed for debugging and audit trails.
Verification references to validate integrity of a result.

What is not shown

API keys, secret keys, signatures, request IDs, internal DB structure.
Raw entropy samples and anti-abuse signals.

Error Codes & Responses

Status	Meaning
200	Successful response
400	Missing/invalid parameters
401	Unauthorized (missing/invalid auth or challenge proof)
403	Forbidden (e.g. inactive account / CSRF failure)
404	Unknown endpoint
409	Conflict (e.g. replay detected)
429	Too many requests / usage cap reached
500	Internal server error

Errors follow: {"error":"..."}

Rate Limiting

The service applies rate limiting and plan-based usage caps to protect reliability. Exact thresholds may evolve; clients should handle 429 with backoff.

Challenge step 1 does not consume a successful randomness call.
Challenge step 2 consumes a call when the proof is valid.
Free tier accounts start with a small monthly allowance.

FAQ

It reduces replay risk and requires proof of possession of the secret key for high-value outputs.

The service prefers quantum sources where available and falls back to a cryptographically secure generator if needed. Responses may indicate whether quantum sources were used.

Yes. It is designed to be shareable and does not include API keys/secret keys or raw entropy samples. For crypto outputs, values may be redacted.

To validate email ownership and reduce abusive registrations. Activate using the emailed link before logging in.

Changelog (short log)

15-12-2025 — Added request log (/requests) + support bundle guidance in public docs.
15-12-2025 — Email activation flow (/register, /activate/{token}).
15-12-2025 — Crypto material mode (?kind=crypto) documented.
10-12-2025 — Implemented **Email Verification Flow** (`/register`, `/activate/{token}`). Accounts are inactive until verified.
10-12-2025 — Implemented **Monthly Rate Limit (Free Tier)** of 5 calls.
8-12-2025 — Added crypto material mode (?kind=crypto) to root endpoint and documented types, params and examples.
20-11-2025 — Added Security & Hardening section; CSP with nonce + strict-dynamic; SRI on Bootstrap; clarified /multi and challenge examples.

Contents

PureRand Quantum Choice Engine — API

Security & Hardening

Authentication

Header Bearer token

Quick Start

cURL — YES/NO (root endpoint)

cURL — Crypto material

2-Step Challenge — flow outline

Endpoints

GET / — Root: choices & numbers

GET / — Crypto material (kind=crypto)

GET /random/{length}/{type} — Stateless 2-step challenge

GET /multi — Unique picks (no replacement)

GET /verify?hash=... — Verify block

GET /ledger — Chain browsing

GET /metrics — Service metrics

GET /requests — Request log (your own history)

POST /register

GET /activate/{token}

POST /login

GET /keys

GET /csrf

POST /rotate_key

GET /me

POST /logout

2-Step Challenge — Details

Request Log

Support bundle (safe to share)

Example shareable JSON

Privacy & Data Exposure

Error Codes & Responses

Rate Limiting

FAQ

Why a 2-step challenge?

What randomness source is used?

Can I share the request log with support?

Why do accounts require activation?

Changelog (short log)

GET `/` — Root: choices & numbers

GET `/` — Crypto material (`kind=crypto`)

GET `/random/{length}/{type}` — Stateless 2-step challenge

GET `/multi` — Unique picks (no replacement)

GET `/verify?hash=...` — Verify block

GET `/ledger` — Chain browsing

GET `/metrics` — Service metrics

GET `/requests` — Request log (your own history)

POST `/register`

GET `/activate/{token}`

POST `/login`

GET `/keys`

GET `/csrf`

POST `/rotate_key`

GET `/me`

POST `/logout`