SparkVault

Secure Entropy v1

Markdown

Overview

The Secure Entropy API provides enterprise-grade, hardware-backed random number generation suitable for cryptographic operations. Unlike software-based PRNGs (which can be predictable if seeded improperly), every request is served by AWS KMS GenerateRandom, which draws from FIPS 140-3 Level 3 validated hardware security modules using a NIST SP800-90A CTR_DRBG with AES-256, seeded from a 384-bit entropy source (these are platform properties of AWS KMS).

For defense-in-depth, the KMS output is XORed with an independent local CSPRNG before it is returned: the hybrid result is at least as random as the stronger of the two sources, so even if one source were compromised the output remains cryptographically secure. There is no software fallback. If the KMS hardware entropy source is unavailable, the request hard-fails rather than degrading to weaker entropy.

FIPS 140-3
Level 3 Validated HSMs
384-bit
Entropy Source
AES-256
CTR_DRBG Algorithm
NIST
SP800-90A Compliant
Cryptographic Grade

This entropy source is suitable for generating encryption keys, session tokens, nonces, salts, and any other application requiring true cryptographic randomness. The underlying AWS KMS DRBG passes NIST statistical randomness tests and provides prediction resistance (guarantees of the AWS KMS platform), and the hybrid XOR construction adds an independent local entropy layer on top.

API Reference

POST /v1/entropy/generate

Generate cryptographically secure random bytes in the specified format.

Authentication

This endpoint accepts standard SparkVault authentication: a session JWT via Authorization: Bearer … or an API key via the X-API-Key header (API keys are prefixed sv_live_). The examples below use API-key auth.

Request Body

ParameterTypeRequiredDescription
format string Optional Output encoding format. See Format Options below for valid values.Default: hex
num_bytes integer Required Number of random bytes to generate. Range: 1-1024 (1-512 for alphanumeric, alphanumeric-mixed, and password). For character-based formats, this is the output length in characters. For uuid, the value is still required and validated but the output always uses 16 bytes.

Response Fields

FieldTypeDescription
value string | array The generated random data in the requested format
format string The format used for encoding
num_bytes integer Number of raw random bytes actually generated. For hex, base64, base64url, numeric, and bytes this equals the requested value. For the character-set formats (alphanumeric, alphanumeric-mixed, password) it is the raw bytes consumed by rejection sampling (2x the requested length). Because the hardware draw is capped at 1024 raw bytes, character-set requests support at most 512 characters; larger values are rejected with 400 VALIDATION_ERROR. For uuid it is always 16, regardless of the request.
reference_id string Unique reference ID for this request (for audit logging)

Format Options

Format Character Set Use Case
hex 0-9, a-f Encryption keys, debugging, hex-based systems
base64 A-Z, a-z, 0-9, +, / General encoding, email-safe data
base64url A-Z, a-z, 0-9, -, _ URLs, tokens, API keys, JWT
alphanumeric A-Z, 0-9 Case-insensitive codes, serial numbers
alphanumeric-mixed A-Z, a-z, 0-9 Case-sensitive codes, identifiers
password A-Z, a-z, 0-9, !@#$%^&*()_+-=[]{}|;:,.<>? Secure password generation
numeric 0-9 PINs, verification codes, OTPs
uuid UUID v4 format Unique identifiers, database keys
bytes Raw byte array (JSON) Direct cryptographic use, custom encoding

Examples

Generate Hex-Encoded Random Data

bash Request 
curl -X POST https://api.sparkvault.com/v1/entropy/generate \
  -H "X-API-Key: sv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "hex",
    "num_bytes": 32
  }'
json Response 
{
  "data": {
    "value": "a3f9b2c8d4e6f1a87b3c5d9e0f2a4b6c8d1e3f5a7b9c0d2e4f6a8b0c2d4e6f80",
    "format": "hex",
    "num_bytes": 32,
    "reference_id": "ent_a1b2c3d4"
  },
  "meta": {
    "api_version": "1.2.828",
    "response_ms": 42,
    "request_id": "9b2f6d1c-4e3a-4c8b-9f0d-2a7e5b1c8d3f",
    "timestamp": 1782864000
  }
}

Generate a UUID

bash Request 
curl -X POST https://api.sparkvault.com/v1/entropy/generate \
  -H "X-API-Key: sv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "uuid",
    "num_bytes": 16
  }'
json Response 
{
  "data": {
    "value": "550e8400-e29b-41d4-a716-446655440000",
    "format": "uuid",
    "num_bytes": 16,
    "reference_id": "ent_b2c3d4e5"
  },
  "meta": {
    "api_version": "1.2.828",
    "response_ms": 38,
    "request_id": "4c7a1e9d-2b5f-4d3a-8c6e-0f9b3a7d5e21",
    "timestamp": 1782864060
  }
}

Generate a Secure Password

bash Request 
curl -X POST https://api.sparkvault.com/v1/entropy/generate \
  -H "X-API-Key: sv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "password",
    "num_bytes": 24
  }'
json Response 
{
  "data": {
    "value": "Kx9!mP@qR2#vL5^nW8&jT3*b",
    "format": "password",
    "num_bytes": 48,
    "reference_id": "ent_c3d4e5f6"
  },
  "meta": {
    "api_version": "1.2.828",
    "response_ms": 35,
    "request_id": "7e3b9f5a-1d8c-4a2e-b6f4-5c0d2e9a1b7c",
    "timestamp": 1782864120
  }
}
Why num_bytes is 48 here

Character-set formats (alphanumeric, alphanumeric-mixed, password) use rejection sampling to avoid modulo bias, so the service consumes 2x the requested bytes and the response echoes the raw bytes consumed. Because the hardware draw is capped at 1024 raw bytes, these formats support at most 512 characters per request. Larger values are rejected with 400 VALIDATION_ERROR. The value is still exactly the requested length in characters (24 here).

Generate a 6-Digit PIN

bash Request 
curl -X POST https://api.sparkvault.com/v1/entropy/generate \
  -H "X-API-Key: sv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "numeric",
    "num_bytes": 6
  }'
json Response 
{
  "data": {
    "value": "847291",
    "format": "numeric",
    "num_bytes": 6,
    "reference_id": "ent_d4e5f6g7"
  },
  "meta": {
    "api_version": "1.2.828",
    "response_ms": 31,
    "request_id": "2a8d4c6f-9e1b-4f7a-a3c5-8b6e0d4f2a19",
    "timestamp": 1782864180
  }
}

Language Examples

JavaScript / Node.js

javascript 
const response = await fetch('https://api.sparkvault.com/v1/entropy/generate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPARKVAULT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    format: 'base64url',
    num_bytes: 32
  })
});

const result = await response.json();
const sessionToken = result.data.value;
console.log('Generated token:', sessionToken);

Python

python 
import os
import requests

response = requests.post(
    'https://api.sparkvault.com/v1/entropy/generate',
    headers={
        'X-API-Key': os.environ['SPARKVAULT_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'format': 'hex',
        'num_bytes': 32
    }
)

result = response.json()
encryption_key = result['data']['value']
print(f"Generated key: {encryption_key}")

Go

go 
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func generateEntropy() (string, error) {
    payload := map[string]interface{}{
        "format":    "base64url",
        "num_bytes": 32,
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST",
        "https://api.sparkvault.com/v1/entropy/generate",
        bytes.NewBuffer(body))

    req.Header.Set("X-API-Key", os.Getenv("SPARKVAULT_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    data := result["data"].(map[string]interface{})
    return data["value"].(string), nil
}

Error Responses

Error Responses

StatusCodeDescription
400 VALIDATION_ERROR Invalid format or num_bytes parameter. Check that format is a valid option and num_bytes is between 1 and 1024.
401 AUTHENTICATION_ERROR Missing or invalid credentials. Provide a session JWT or a valid X-API-Key header.
402 PLAN_REQUIRED An active subscription is required for this operation. Subscribe to continue.
402 QUOTA_EXCEEDED The account bandwidth pool is exhausted (details include resource: bandwidth). Add a capacity block to continue.
429 RATE_LIMIT_EXCEEDED Too many requests. Wait and retry. Check Retry-After header.
500 CRYPTOGRAPHIC_ERROR Entropy generation failed because the KMS hardware entropy source was unavailable. There is no software fallback. This is rare. Retry the request.

A 503 response can only originate from upstream infrastructure, not from the API itself; such responses do not carry the SparkVault error envelope or an error code. Retry with exponential backoff.

Usage

Operation Usage
Entropy Generation (any format, any size) Draws pooled bandwidth (included with subscription)

Entropy generation is covered by your seat subscription and tracked as usage. Each customer call also draws the account bandwidth pool by its request plus response size; there is no per-request charge. Requests are subject to your plan's rate limits regardless of the number of bytes requested (up to the 1024 byte limit). When the bandwidth pool is exhausted, the call is refused with 402 QUOTA_EXCEEDED; extend the pool with a capacity block to continue.

Try It

You can test secure entropy generation interactively in the SparkVault dashboard. Open the Entropy panel from the dashboard shortcut, the command palette, or the console footer.

Open Dashboard