# 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.

## Related Patterns

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