Pattern: Idempotent Command API

Status: seed Readiness target: RL2 private beta Primary owners: product repos Genesis family: Application/API security

Problem

Retries, duplicate submissions, and partial failures can create unsafe state changes when command APIs are not idempotent.

Context

Use this pattern for payment-like operations, provisioning, tenant configuration, file processing, job submission, and external callbacks.

Forces

Networks and clients retry requests.
Commands need audit and correlation.
Duplicate execution can create data or authorization errors.
Some commands must be scoped to actor and tenant.

Solution

Require command identifiers and replay-safe semantics for state-changing operations. Bind idempotency keys to actor, tenant, command type, and resource scope.

Verification

Replaying a command id returns the prior result or safe status.
Idempotency keys cannot be reused across tenants or actors.
Command audit records include correlation id and outcome.
Partial failures are recoverable without duplicate effects.

Tenant Context Propagation.
Central Audit Ledger.
Schema-First API Security.
Incident Runbook Library.

1.2 KiB Raw Blame History