API-key and JWT Verifier Generations¶
openmed.service.auth_generations rotates REST API-key hashes and JWT verification keys without restarting the service. The caller supplies each complete set of verifiers as one generation. OpenMed validates the whole generation, publishes it as one immutable snapshot, and keeps the previous generation only for a bounded overlap window. A rejected reload never changes what is active.
This feature owns the verifier lifecycle only. It does not reload TLS or mTLS certificates, issue tokens, or discover keys from an identity provider. Key custody stays with the caller, and nothing here makes network calls.
Generation contents¶
A generation is a VerifierGenerationSpec or an equivalent JSON document:
{
"generation_id": "2026-10-rotation",
"serial": 7,
"api_keys": [
{
"id": "clinic-api",
"principal": "clinic-api",
"key_hash": "sha256:<sha256-hex-digest>",
"scopes": ["pii:read"]
}
],
"jwks": {"keys": [{"kty": "RSA", "kid": "rs-2026-10", "alg": "RS256",
"n": "<base64url>", "e": "AQAB"}]},
"jwt": {
"issuer": "https://issuer.example.invalid",
"audience": ["openmed"],
"leeway_seconds": 30,
"max_lifetime_seconds": 900
}
}
api_keys and jwks use the same shapes as OPENMED_SERVICE_AUTH_API_KEYS and OPENMED_SERVICE_AUTH_JWKS (see REST Authentication) and are parsed by the same functions. Token checks reuse authenticate_api_key and authenticate_jwt from openmed.service.auth; the signature, exp/nbf/iat, issuer, audience and lifetime rules are unchanged.
A generation is complete only when all of these hold:
generation_idis 1-64 ASCII letters, digits,.,_,:or-, andserialis a positive integer.- It holds at least one API key or JWK.
- API-key hashes are
sha256:<64 hex>; key IDs and hashes are unique. - Every JWK has a unique
kid, isoct/HS256 orRSA/RS256 withuseabsent orsig, and carries no private members (d,p,q,dp,dq,qi,oth). - HS256 secrets are at least 32 bytes. RSA moduli are at least 2048 bits by default (
min_rsa_modulus_bits, floor 1024) with an odd exponent of 3 or more. - When JWKS are present, an issuer and at least one audience are set. Leeway is 0-300 seconds and the maximum token lifetime is finite and positive.
Lifecycle¶
from openmed.service.auth_generations import VerifierGenerationRegistry
registry = VerifierGenerationRegistry(max_overlap_seconds=3600)
receipt = registry.reload(generation_document) # first generation
receipt = registry.reload(next_document, overlap_seconds=600) # rotate
if not receipt.accepted:
print(receipt.reason) # fixed code; the last valid generation stays active
| Operation | Effect |
|---|---|
stage(spec) | Validate and hold a generation without accepting it. |
activate(generation_id, overlap_seconds=...) | Atomically make a staged generation active. |
reload(spec, overlap_seconds=...) | Validate and activate in one step. |
revoke(generation_id) | Stop accepting a staged, active or overlapping generation now. |
status() / metrics() | Labels, serials, epochs, boundaries and counters only. |
Rules that keep rotation bounded:
serialmust increase on every activation, so an older generation cannot be replayed. A generation ID cannot be reused while it is known to the registry or among the last 256 accepted IDs.overlap_secondsmust be between 0 andmax_overlap_seconds. With 0 the previous generation stops immediately. Otherwise it is accepted whilenow < retire_atand rejected fromretire_aton.- At most one previous generation overlaps. Activating again drops any older overlapping generation.
- During an overlap, a credential carried over from the previous generation must be identical. The same key hash with a different key ID, principal or scopes (
api_key_conflict), or the samekidwith different key material (jwk_kid_conflict), is rejected. Changing a key's scopes needs a zero-overlap cutover or a new key. - Revoking the active generation fails closed: requests are rejected until another generation is activated. Revocation works even if the clock fails.
The clock is injected (clock=, default time.time). JWT time claims and overlap boundaries use the same reading for each decision. A non-finite or non-numeric reading rejects lifecycle changes with clock_invalid and rejects authentication.
Pinned decisions¶
Lifecycle changes are serialized and publish a new snapshot with one reference assignment. Each decision reads one snapshot and checks the active generation, then the overlapping one. Every check runs against a single generation's keys and JWT bounds. authenticate_api_key and authenticate_bearer return a GenerationDecision whose pin records the generation ID, serial, snapshot epoch and role (active or overlap). registry.view() returns a view pinned to one snapshot for callers that need several consistent checks. Inputs are deep-copied at validation, so changing the caller's objects later has no effect.
To use generations in the REST service, replace the app's auth middleware. The service reads app.state.auth on every request:
from openmed.service.app import create_app
from openmed.service.auth_generations import GenerationalServiceAuth
app = create_app()
app.state.auth = GenerationalServiceAuth.replacing(app.state.auth, registry=registry)
Route scopes, exempt paths and failure rate limits still come from the OPENMED_SERVICE_AUTH_* settings. API keys and JWKS come only from the registry. Authenticated requests carry the GenerationPin in request.state.auth_generation and request.scope["openmed.auth_generation"]. Failures return the same 401 invalid_credentials envelope as static auth.
Privacy of receipts and diagnostics¶
Every lifecycle call returns a GenerationReceipt with the action, outcome, fixed reason code, epoch, clock time, generation ID and serial (only for a validated or known generation), overlap boundary, key counts, and a canonical sha256: digest over those fields. Receipts, status(), metrics(), object representations and GenerationValidationError never contain raw API keys, key hashes, JWK material, tokens, token claims, principals or invalid input values. Errors raised from validation carry no chained exception context.
Reason codes: document_malformed, document_field_unknown, generation_id_invalid, generation_serial_invalid, generation_serial_stale, generation_id_reused, generation_empty, generation_unknown, api_keys_malformed, api_key_hash_invalid, api_key_duplicate, api_key_conflict, jwks_malformed, jwk_unsupported, jwk_kid_missing, jwk_kid_duplicate, jwk_kid_conflict, jwk_private_material, jwk_key_invalid, jwk_key_too_weak, jwt_binding_incomplete, jwt_leeway_invalid, jwt_lifetime_invalid, overlap_out_of_bounds, staged_capacity_exceeded, clock_invalid.
Metrics are counters keyed by <action>_accepted, <action>_rejected:<reason>, decision_active, decision_overlap, decision_rejected, decision_no_active_generation and decision_clock_invalid.
Validation¶
The tests use synthetic keys and an injected clock. They cover overlap admission and rejection at the boundary, malformed and conflicting generations, revocation, stale serials, caller mutation, a multi-threaded reload test that fails if a reader ever sees a partial key set, sentinel leak checks, and REST middleware rotation without a restart.