How to use idempotency
Make a retry safe.
The problem
You POST an issuance. The connection times out. Did it work?
Without idempotency you cannot tell, and both choices are bad: retry and you might issue a second credential; do not retry and the holder may never get theirs.
The fix
POST /v1.0/credentials/issuance
Idempotency-Key: order-4417
| You send | You get |
|---|---|
| Same key, same payload | The original result, replayed |
| Same key, different payload | 409 |
| New key | A new operation |
Retrying becomes safe: at worst you get the original answer back.
Choose the key from your own data
Idempotency-Key: order-4417
Idempotency-Key: enrolment-2026-a41f9
Derive it from the business fact the call represents — an order number, an enrolment identifier. Generate it once, before the first attempt, and reuse it for every retry.
Do not generate a fresh UUID per attempt. That is the single most common mistake, and it defeats the mechanism completely: every retry looks like a new request.
Why a different payload is a 409
If the same key returned the original result regardless of payload, a genuine bug — two different orders assigned the same key — would silently return the wrong credential to the wrong person. Failing loudly is better.
Scope
A key is scoped to your tenant, your API key and the operation. It cannot collide with another customer's, and it cannot be replayed against a different operation.
It works identically on /v1.0 and /v1, so a retry that starts on one and finishes on the other still
deduplicates.
Which operations accept it
Those whose reference page lists Idempotency-Key in the request headers — issuance, verification creation and
the equivalent transaction operations. Reads do not need it.