Idempotency
Mutating operations accept an Idempotency-Key header so a retry after a timeout or a network failure cannot
create a duplicate.
POST /v1/credentials/issuance
Idempotency-Key: 8f14e45f-ea0b-4f2b-9d1e-7c3a2b6d5e01
Use a fresh value per logical operation — a UUID is ideal. Never reuse one across different operations.
Behaviour
| Situation | Result |
|---|---|
| First request with this key | Processed normally, and the result is recorded |
| Same key, same payload | The original result is replayed; nothing new is created |
| Same key, different payload | 409 idempotency_conflict — the earlier result is not returned |
| No key supplied | Processed normally; retries may duplicate |
A key is scoped to your tenant, your API client and the specific operation. The same key used for issuance and for verification is two independent records, not a collision.
Records are retained for 24 hours. After that the key is forgotten and reusing it starts a new operation.
Only a hash of the request is stored, never the request body — replay needs proof the payload matched, not the payload itself. Claims and subject data are not retained by this mechanism.
Supported operations
POST /v1/credentials/issuancePOST /v1/verifications
Other mutating operations are safe to retry for other reasons or do not yet participate; supplying a key to them is harmless but has no effect.
Recommended retry policy
Retry 429, 503 and network failures with exponential backoff and jitter, carrying the same
Idempotency-Key each time. Do not retry 400, 401, 403 or 409 — retrying will not change the outcome.