GET

Public entropy

Get source verification key

/api/v2/entropy/source-key

AUTHENTICATIONNone · publicService ownerentropy-serviceContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Return the gateway-pinned Ed25519 public JWK used to verify physical-source sample envelopes without exposing source credentials or private key material.

When to use it

Fetch before verifying a source-signed sample and again whenever the catalog, source ID, or key ID changes.

OUTCOME · Verify

What changes

Read-only projection; it grants no mutation, settlement, traffic, or authority change.

WHY IT MATTERS

Gives people and agents a contract-backed way to verify source verification key.
Provides bounded, nonce-bound physical entropy with a verifiable source envelope while keeping source credentials and private signing material isolated.

ISOLATION + AUTHORITY

Caller authorization, nonce, requested byte count, physical source, source key, signed envelope, consumer conditioning, application randomness model, and downstream cryptographic use remain distinct. A valid source signature proves envelope provenance and integrity, not fitness for every cryptographic protocol or permission to perform a downstream action.

BEFORE YOU CALL

No bearer credential is required; apply bounded filters and canonical public identifiers where the contract provides them.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Resolve the required assurance and byte count, fetch the current source key, generate a fresh caller nonce, and define the consuming application's conditioning and replay policy.

WHAT TO DO NEXT

Fetch the current source key and request only the minimum sample size with a fresh caller nonce.
Verify the returned envelope and apply the consuming application's conditioning, health, and replay policy before use.

AGENT GUIDANCE

Use source verification key only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Validate source ID, key ID, signature, nonce echo, byte count, encoding, freshness, and replay posture, then apply the consuming application's required conditioning and health policy.
Use response links and canonical identifiers instead of constructing internal service URLs or scraping the website.

Contract reference

Use the deployed OpenAPI for exact parameters, schemas and security requirements. The tables below provide integration guidance.

Open this operation in OpenAPI

Request and response

Make the request

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

RESPONSES

Status and payload examples

200Gateway-pinned Ed25519 public JWK for the configured physical entropy source.Read completed · JSON RESPONSE+

{
  "schema": "hybrid.entropy.source-key.v2",
  "source_id": "qse-production-1",
  "key": {
    "kty": "OKP",
    "crv": "Ed25519",
    "kid": "qse-ed25519-7kYp9bW2Qn4rT8cD",
    "x": "base64url-public-key-bytes"
  }
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then fetch the current source key and request only the minimum sample size with a fresh caller nonce.
RETRY SAFETY: Repeat only when the integration needs a fresher authoritative projection.
STATE RECONCILIATION: Use returned identifiers and versions as the comparison point for later reads. Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.

503No authoritative source verification key is configured.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "entropy_source_unavailable",
  "message": "No authoritative source verification key is configured."
}

INTEGRATION DECISIONentropy_source_unavailable

CALLER ACTION: Treat the failure as transient and preserve the last known good representation without presenting it as fresh.
RETRY SAFETY: Retry with bounded exponential backoff and jitter; stop after the integration's failure budget is exhausted.
STATE RECONCILIATION: Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

OPERATIONAL NOTES

Security and lifecycle guarantees

Pin source_id, key.kid, and key.x. A returned sample is acceptable only when data.source_id, data.source_key_id, and proof.key_id match this document and the Ed25519 signature verifies.
key.x is an unpadded base64url Ed25519 public key. It is not a private key, Transit RSA key, encryption key, wallet key, or authorization credential.
Re-fetch on key-ID or catalog changes. Rotation policy and historical-key discovery are not implied by this current-key endpoint. The response is public and no-store.

Reference version and availability details

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-10-02T23:27:55.510Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation Return to the V2 directory