Cybersecurity glossary
What is an Idempotency Key?
Learn what an idempotency key is, how clients use it to retry POST requests safely, how servers store and compare keys, and which security rules prevent key misuse.
Definition
An idempotency key is a client-generated unique token sent with an API request—usually in a header—so the server can recognize retries of the same intended operation and return the original result instead of applying the side effect again.
Why idempotency keys exist
PUT can target a known resource ID. Many real operations cannot: “charge this card,” “submit this order,” “start this scan.” Those are naturally POST-shaped—and POST is not idempotent by default.
An idempotency key gives that POST a stable identity. The first successful processing stores the result under the key; later retries with the same key replay the stored outcome.
How an idempotency key request flows
Client creates a key for one user intent
Generate before the first attempt—e.g., when the user clicks Pay—not after a timeout.
Send the write with the key
Include Idempotency-Key on the POST along with the payload and auth credentials.
Server looks up the key in a scoped store
Lookup is bound to tenant/user/API key so keys are not global across customers.
First seen: execute and persist
Apply the side effect once, store response status/body (and payload hash) atomically with the key.
Retry seen: return stored result
Do not charge again; return the original success or failure response.
Mismatch or in-progress states handled
Different body → conflict. Concurrent first attempts → lock or wait until one finishes.
What to store with each key
Key and owner scope
Key string plus tenant/user/app identity that presented it.
Request fingerprint
Hash of method, path, and body (and critical headers) to detect mismatches.
Response snapshot
Status code and body needed to replay an identical client outcome.
Lifecycle metadata
Created-at, expires-at, and in-progress vs completed state for concurrency.
Client and server responsibilities
| Side | Must do | Must not |
|---|---|---|
| Client | Generate key per logical action; reuse on retries | Reuse the same key for a different payment or order |
| Server | Dedupe under scope; compare payload fingerprints | Trust keys as authentication or cross-tenant capability tokens |
| Both | Document retention window and conflict behavior | Assume network success means the user saw the response |
Security rules for keys
Scope keys to the caller
Never let user A retrieve user B’s stored response by guessing a key.
High entropy values
Prefer UUIDs or secure random strings; avoid short sequential IDs.
Reject payload mismatches
Same key, different body → 409 (or equivalent), never a silent second operation.
Authorize before replay
If the caller lost permission, do not replay a privileged stored success blindly—follow your threat model explicitly.
Implementation checklist
- Pick a header name (Idempotency-Key is common) and document it in the API guide.
- Require keys on money-moving and other high-impact POST endpoints.
- Store keys with tenant scope, payload hash, response, and expiry.
- Make first-insert concurrency-safe (unique constraint or atomic lock).
- Define behavior for in-progress duplicates (wait, 409, or 425/429-style retry guidance).
- Expire keys on a published schedule; monitor storage growth.
- Add integration tests for timeout-retry, mismatch body, and cross-user key reuse attempts.
- Educate frontend teams to mint keys at intent time, not per HTTP attempt randomly.
The practical takeaway
An idempotency key is how APIs make POST-like operations safely retryable. Clients name an intent once; servers remember the outcome and suppress duplicate side effects.
Implement keys with scoped storage, payload comparison, and clear conflict semantics. Done right, flaky networks stop creating double charges—and attackers replaying requests stop amplifying damage.
Related security terms
Idempotency
The broader property that idempotency keys help enforce for non-idempotent operations.
HTTP Method
POST and some PATCH flows are the usual place keys are introduced.
HTTP Status Code
409 Conflict is commonly used when a key is reused with a different payload.
Race Condition
Concurrent first-time requests with the same key need atomic handling.
Webhook
Related deduplication patterns using event IDs instead of client keys.
Frequently asked questions
What is an idempotency key in simple terms?
It is a unique ID the client invents for one user action—like “create this payment”—so if the phone retries after a glitch, the server recognizes it as the same action.
Where is the key sent?
Commonly in an Idempotency-Key HTTP header, sometimes in a JSON field. Headers keep bodies identical across retries.
Who generates the key?
The client (or BFF) should generate it before the first attempt and reuse it on retries of that same intent.
How long should servers remember keys?
Long enough to cover realistic retries—often 24 hours for payments—then expire to bound storage. Document the window clearly.
What if the same key is sent with a different body?
Treat it as a client error, typically 409 Conflict. Do not silently execute a different operation under the old key.
Are UUIDs required?
Any high-entropy unique string works. UUIDv4 is a common choice; predictable sequential keys are easier to collide or guess within a tenant.
Do GET requests need idempotency keys?
Usually no. GETs should already be idempotent. Keys are for operations that would otherwise create new side effects each time.
References
Explore authoritative guidance and frameworks related to idempotency key.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.