Source: docs/integration/idempotency.md

Idempotency

Capability imports

Every POST /v1/capabilities/import request requires an Idempotency-Key

header. Generate one key for a single logical import and reuse that exact key

when retrying the same request.

-H "Idempotency-Key: capability-import-$(date +%s)"

A repeated import with the same key returns the previous result and includes

Idempotency-Replayed: true; it does not create a second capability revision.

Use a new key only for a new logical import, such as one containing a revised

manifest.

Action decisions

Approval and rejection also require an Idempotency-Key. The key is scoped to

the access bundle and stored with a request hash, action ID, operation, status,

and redacted response. Reusing the same key with a different action, operation,

or subject returns 409 IDEMPOTENCY_KEY_REUSED.

A capability mutation receives the stable idempotency_key persisted when its

pending action was created. Forgium sends it as the manifest's

idempotency_header, or Idempotency-Key when no custom header is declared.

Forgium never retries a live mutation automatically.