Key recovery

Ordered runbook for lost key material — idempotency replay, orderReference re-reveal, bulk export, and when to escalate to support.

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.

Where key plaintext can be read#

Key plaintext is returned by the response of the call that sold the keys (POST /orders, and the other order and pull writes), by an idempotent replay of that call, and by POST /orders/recover-keys, which re-reads keys you already bought. 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.

Step 1 — Replay with the same Idempotency-Key#

Retry POST /orders with the same Idempotency-Key and the identical JSON body. Within the 24-hour replay window the original response — including key plaintext — is returned with Idempotency-Replayed: true and no second side effect. If the original request never executed, it executes now. Either way you end with exactly one order.

Step 2 — Look the order up#

If the replay window has passed, the key was lost, or retries keep failing, ask whether the order exists:

Bash
curl -s "https://api.avrix.io/api/seller/v1/orders?orderReference=store-order-10432" \
  -H "Authorization: Bearer avrix_sk_your_key_here"

The lookup never returns plaintext. It tells you which step comes next: the order was fulfilled (step 3) or it does not exist (step 4). An order that is still waiting (awaiting_stock, awaiting_release, ready) has delivered no keys yet: follow Order lifecycle instead.

Step 3 — Re-read the keys with POST /orders/recover-keys#

When the order was fulfilled and you do not hold its keys:

Bash
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/recover-keys" \
  -H "Authorization: Bearer avrix_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "orderReference": "store-order-10432" }'
JSON
{
  "data": {
    "orderReference": "store-order-10432",
    "recovered": 1,
    "keyIds": ["8f21a9b0-1234-5678-9abc-def012345678"],
    "keys": ["AAAAA-BBBBB-CCCCC"],
    "skuIds": ["3f9a1c22-7b6d-4e51-9f0a-2c8e4d6b1a35"],
    "revoked": [],
    "frozen": []
  }
}
  • It returns the keys that are still live under that orderReference. It never pulls new inventory and is never a new sale; every call is recorded as a key reveal.
  • Scope: seller:keys:pull (or seller:orders:write). No Idempotency-Key is needed; the call is safe to repeat.
  • Returned and refunded keys are not included. Keys the Content Owner revoked are listed under revoked[] and keys frozen by an open dispute under frozen[], in both cases without plaintext.
  • 404 NOT_FOUND means nothing can be read under the reference: the order never fulfilled, every key was returned or refunded, every key was revoked (details.revoked), or every live key is frozen (details.frozen).
  • On contract date 2026-10-01 and later, keys holds typed key objects instead of strings (Fulfilment keys).

A POST /orders sent again with the same orderReference, the same SKU and the same quantity also answers with the original keys and consumes no inventory, so a retry that lost its idempotency record does not sell twice. A different quantity answers 409 ORDER_REFERENCE_CONFLICT. Prefer recover-keys for recovery: it needs no price binding and works after a partial refund.

Step 4 — The order does not exist#

If the lookup shows no order under the reference, the original request never committed. Send the same request again — same Idempotency-Key, same body, same orderReference — and it places the order; or refund the buyer at your payment processor. Refund only when the lookup shows no live keys for the reference. Do not change the orderReference: it is what stops a second sale if the first request turns out to have committed after all.

Step 5 — Support escalation#

When the steps above cannot recover (for example, recover-keys keeps answering 5xx), 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.

What is not a recovery path#

POST /keys/export and POST /keys/pull pull new keys from an allocation: each call is a new sale that is billed. POST /keys/export returns them as a ZIP file and needs the opt-in seller:keys:export scope. Neither re-reads keys you already bought; use recover-keys for that, one orderReference at a time.

Deferred reveal#

If you deliberately ordered with immediateFulfilment: false (deferred reveal), the plaintext was never in the response. recover-keys is also how you read those keys, with the same orderReference and the same answers as above; see Fulfilment and keys.

What links here

Published guides that link to this page.

Search docs

Search documentation…