This page documents how replay protection is currently enforced for API-key authentication.
Scope
Applies to API-key (Ed25519) authenticated requests.
Does not apply to JWT client flows.
Enforced on write/money-moving API paths.
Not enforced on read-only paths at this time.
Current policy
Timestamp freshness window for API-key requests is 10 seconds.
Replay dedupe is enabled only for write paths that opt in.
Dedupe is performed in-process (per instance) using an in-memory TTL cache.
Consequence in multi-instance deployments
Replay protection is strongest when the replay attempt lands on the same instance.
Cross-instance replay can still pass unless you use a shared dedupe backend.
Why write-only replay enforcement
This is a latency-security tradeoff:
Write endpoints have higher financial impact and benefit most from replay protection.
Read endpoints are lower risk and high volume, so avoiding extra hot-path overhead helps keep tail latency low.
Client guidance
Always send
X-API-NONCEfor private API-key calls.Keep clocks synchronized (NTP strongly recommended).
Use short-lived retries and idempotency patterns on write flows.
Future direction
Potential upgrades if stricter guarantees are required:
shared replay store across instances (Redis/Valkey)
endpoint-specific policy levels (strict replay everywhere vs write-only)
explicit replay error taxonomy (for example, dedicated replay code)