Key points
- Use a CSPRNG-backed service for security-sensitive bytes, bounded numbers, shuffling, and sampling.
- Define the operation, range, quantity, and failure behavior before integrating the endpoint.
- Treat evidence receipts as proof of what the service recorded, not as a public proof that predicts or reconstructs the random value.
CSPRNG is a security property, not a visual pattern
A cryptographically secure pseudorandom number generator is designed so that observing prior output does not make future output practically predictable. This is different from a general-purpose pseudorandom generator used for reproducible simulations, where a known seed is often a feature.
An API should expose unambiguous operations instead of forcing every customer to convert raw bytes independently. Rantropy supports random bytes, bounded numbers, shuffling, sampling, and distribution workflows through REST and gRPC. The operation selected by the client remains part of the usage and evidence context.
Integration decisions to make before the first request
Start by separating security material from business randomness. Session secrets and cryptographic nonces need byte-oriented output and strict handling. Draws, probability items, and sampling need explicit ranges, list sizes, replacement rules, and error behavior.
- Choose REST for broad compatibility or gRPC for persistent server-to-server traffic.
- Set request timeouts, retry rules, and idempotency behavior for the business operation.
- Keep API keys in a secret manager and issue separate keys for environments or services.
- Decide whether each request needs a receipt and how long the evidence must be retained.
Call the REST endpoint with an explicit byte count
The random-bytes operation accepts a JSON count. Its REST JSON response represents the protobuf bytes field as base64, while randomnessBytesConsumed reports the billable random-byte quantity for the operation.
The receiptId field is present only when receipt generation is enabled for the contract and request. Clients should treat it as optional and must not assume that a successful random response always includes a receipt.
curl --request POST "$RANTROPY_REST_URL/v1/random/bytes" \
--header "content-type: application/json" \
--header "x-api-key: $RANTROPY_API_KEY" \
--header "x-api-secret: $RANTROPY_API_SECRET" \
--data '{"count":32}'{
"response": {
"success": true
},
"data": "<base64-encoded-random-bytes>",
"randomnessBytesConsumed": 32,
"receiptId": "<receipt-id-when-enabled>"
}What Rantropy verification does and does not claim
Rantropy connects a request, its result hash, usage information, and timing to a reviewable receipt. Hash chains and Merkle proofs can make later deletion or modification detectable when the relevant plan and receipt policy enable them.
This evidence model is not the same as a verifiable random function, a public randomness beacon, or a commit-reveal protocol. Those systems answer different questions, such as proving a value from a public key or preventing either participant from choosing the final seed alone. Select the model that matches the threat being controlled.
Operational checks after integration
Monitor latency and errors by operation, not only at the load balancer. Reconcile API usage with contract limits, verify receipt retrieval on a schedule, and test key rotation before an incident. For high-volume systems, test with the intended key count and receipt-on ratio because asynchronous evidence work can be a separate capacity constraint.