Key recovery

Your buyer paid, your POST /orders call happened — and the response with the key plaintext is gone: a crash mid-request, a dropped connection, a deploy at the wrong second. This page is the complete, ordered recovery procedure. Work it top to bottom; each step is strictly safer than inventing a new order.

Key plaintext exists in exactly one place on the wire: the synchronous response of POST /orders (and the pull/export responses below). It is never available via:

• webhooks — payloads are redacted by design (order.fulfilled carries key ids, not codes);
• GET /orders — lookup and listing responses carry key ids only;
• delivery replay — replays are clones of redacted payloads.

If a path promises key plaintext outside the synchronous responses listed below, it is wrong.

Retry POST /orders with the same Idempotency-Key and the identical JSON body. Within the 24-hour replay window the cached response — including key plaintext — is returned with Idempotency-Replayed: true and no second side effect.

If the idempotency window has passed (or the key was lost), submit POST /orders with a new Idempotency-Key but the same orderReference, the same allocation/SKU, and the same quantity. When the reference already has enough live keys, Avrix re-reveals the original keys' plaintext — no additional inventory is consumed.

• Replay requires the requested quantity to be covered by the prior fulfilment. A larger quantity returns 409 ORDER_REFERENCE_CONFLICT — there is no top-up.
• Scope is per allocation: the same reference on a different allocation is a different pull.

For batch recovery (for example, rebuilding an entitlement vault), POST /keys/export returns a ZIP of the plaintext for keys your company already pulled. Requires the seller:keys:export scope and an Idempotency-Key; every 2xx is always audited.

When the steps above cannot recover (for example, the original request never committed), contact support@avrix.io with:

• the X-Request-Id of the failed call (or requestId from the error body),
• the Idempotency-Key and orderReference you used,
• the approximate timestamp with timezone.

Avrix can trace exactly what the request did — including whether keys were issued — from the request id alone.

If you deliberately ordered with immediateFulfilment: false (deferred reveal), the plaintext was never in the response; reveal follows the deferred reveal contract instead of this runbook.

• Idempotency — the full retry contract
• Order lifecycle — states and events
• Fulfilment keys — custody model
• Troubleshooting