Idempotent business commands
Keep idempotency keys inside the correct account scope
A retry key identifies an intention, not a user. Authenticate the caller and scope result lookup so one account cannot retrieve or suppress another account's operation.
In this article
Choose a namespace that matches authority
Use a uniqueness rule such as account, operation type and key. Derive account scope from trusted authentication context rather than accepting an arbitrary account field from the request body.
Without appropriate scope, two customers using the same key can collide. The result may be an incorrect conflict, suppression of legitimate work or disclosure of a stored response belonging to someone else.
Keep operation type in the namespace where the contract requires it. A key used to create a booking should not accidentally retrieve a result from an unrelated command.
Recheck access when returning a result
A matching key should not bypass authorisation. The caller still needs permission to inspect the operation and its result, especially if roles or target access changed after the original request.
Store only the response data needed to reproduce the documented result. A full internal record can retain sensitive fields that the public response never needed.
Protect status endpoints and support tools with the same scope. Hiding a result in the main API is insufficient if a diagnostic lookup accepts the key without checking the account.
Avoid sensitive information in keys
Use opaque identifiers with sufficient uniqueness for the system's scale. Do not encode email addresses, personal names or secrets merely to make keys readable in logs.
A key may appear in tracing, headers and support records, so treat it as potentially visible metadata. It should not act as a bearer credential that grants access by possession alone.
Review retention of payload fingerprints and stored results. Even a fingerprint or identifier can have a data-handling role depending on what it links to, so document its purpose and access rules.
Test collisions and changed authority
Submit the same key from two accounts and verify each receives the intended independent behaviour without cross-account disclosure. Repeat with one account attempting to name the other's target.
After a successful request, remove the caller's access and test result retrieval under the documented policy. Also inspect operator lookup paths.
The review should establish that idempotency preserves one action within an authorised scope. It must not become a shortcut around the access checks that apply to the underlying business record.
Primary sources
OWASP: authorisation guidanceStripe: idempotent requestsReferences checked 11 September 2026.