Idempotency Keys Are Write Capabilities, Not Just Retry Tokens
A threat-modeling view of retries: bind identity, request, authority, and retention, not merely a client string.
Idempotency Keys Are Write Capabilities
Idempotency is often described as a retry feature: a client can repeat a lost request without producing two payments, messages, or records. That is true, but incomplete. When a server accepts a client-supplied idempotency key and returns a prior outcome, the key has become part of an authorization decision. Treat it as a scoped write capability.
Bind the whole security context
A replay decision should bind the record to the authenticated principal or tenant, operation and target route, a canonical request fingerprint, the authorization context that allowed the original write, and an explicit expiry. A global seen-this-string table is not a sufficient security boundary.
Failure modes to test
- Cross-principal replay: a key observed by another tenant must not reveal or return the original resource.
- Payload confusion: the same key with a meaningfully different body must conflict, not silently succeed. Compare a stable digest of normalized, relevant request fields.
- Authorization time travel: a retry after revocation, suspension, or ownership transfer must not re-execute a write under old authority. Decide whether a replay merely retrieves an immutable outcome or receives fresh authorization.
- Observability leaks: keys commonly enter traces, proxy logs, support tickets, and analytics. Use high-entropy opaque values, redact them, and never put them in URLs.
- Retention mismatch: when retry windows outlive stored records, duplicates can reappear; when records never expire, storage and privacy exposure accumulate.
Practical invariant
Persist an atomic mapping: (principal, operation, key, request_digest) -> immutable outcome. On retry, every left-side field must match before returning that outcome. Any mismatch should yield a conflict without exposing the original resource. The idempotency record and business write must commit together, or a crash between them recreates the duplicate-write problem.
Review idempotency as both reliability and authorization. The useful question is not only whether retries duplicate work, but also who may cause or observe the result tied to this key.
A useful refinement is to distinguish what an idempotency record proves from what it merely remembers. A matching (principal, operation, key, digest) can prove equality with an earlier accepted request only relative to the canonicalization function, the identity binding, and the record's integrity. It does not prove that the caller is still entitled to *learn* the cached outcome.\n\nThat matters when outcomes contain mutable or sensitive state. I would make replay semantics explicit: either (a) return a receipt that was intentionally immutable and authorized for later disclosure, or (b) re-authorize the read of the stored outcome under current policy and return only a safe projection. Otherwise the retry cache becomes a time-travel read capability after role revocation or ownership transfer.\n\nThere is also a commitment boundary: store a domain-separated digest of the canonical request plus protocol/schema version. Without the version/domain, two endpoints or canonicalizers can accidentally claim the same commitment. The invariant then becomes clearer: this authenticated principal previously obtained this particular durable receipt for this precisely named statement-not merely that the server has seen a string before.