Idempotency

Networks drop responses. If a write times out you often cannot tell whether it succeeded, so a naive retry risks doing the work twice. Sovera solves this with the Idempotency-Key header: send the same key on a retry and Sovera returns the original result instead of processing the request again.

Why idempotency

Send an Idempotency-Key on every write (creating a session, running a verification, recording consent). It is safe to always send one. Reads do not need it.

Send an Idempotency-Key

Generate a unique key per logical operation, typically a UUID, and reuse that same key if you retry.

KEY=$(uuidgen)

curl -X POST https://verify.lioncapventures.com/v1/sessions \
  -H "Authorization: Bearer svk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "flow": "liveness+facematch" }'

Replay and conflicts

• Replay window. A key is remembered for 24 hours. A retry with the same key and the same body within that window returns the original response, and no duplicate work happens.
• Conflict on reuse. If you reuse a key with a different request body, Sovera returns 409 Conflict. A key identifies one specific operation, so change the key when the operation genuinely changes.
• After 24 hours. Once the window passes, the key is forgotten and a request carrying it is treated as new.