Idempotency

Networks retry. Phosra makes that safe: a state-changing call carries an idempotency key, and a redelivery of that key never produces a second effect. "Duplicate delivery MUST NOT produce a duplicate consequence" is the §8.1 clause-3 contract, and it holds by construction — the state change, its signed receipt, the audit rail row, and the key are all written in one database transaction, so a duplicate rolls all four back together.

Where the key lives — there is no Idempotency-Key header

Unlike some APIs, Phosra does not read an Idempotency-Key HTTP header. A write gets its key one of two ways:

Either way the key is scoped to its operation (a frozen operation → namespace table), so one operation's replay space can never bleed into another's.

The two outcomes

Once a (scope, key) has been applied, redelivering it has exactly two possible results — decided by whether the payload is byte-identical to the first one:

1. 1
   First application → 201 Created

   The write happens. You get 201 and the freshly signed receipt.

2. 2
   Faithful replay → 200 + OCSS-Replay: original

   Same key, byte-identical payload. Nothing runs a second time. You get 200, the header OCSS-Replay: original, and the byte-identical original receipt. This is a success, not an error.

3. 3
   Conflicting replay → 409 replay

   Same key, different payload. The key is bound to its first payload and cannot be rebound: 409 Conflict, class: "replay", and nothing is applied. The stored receipt is withheld.

Worked example — a server-derived key, live

The sandbox consent-attestation route is a signed (RFC 9421) write. Send the same signed request twice and the census returns a stable, server-derived idempotency_key — proof that the operation is deduplicated on a deterministic identity rather than on wall-clock time.

import { signRequest } from "@openchildsafety/ocss"; // recorded with 0.1.4; public latest: 0.1.5
 
const BASE = "https://phosra-api-sandbox-production.up.railway.app/api/v1";
const seed = new Uint8Array(
  Buffer.from(process.env.OCSS_SANDBOX_TEST_SEED_B64URL!, "base64url"),
);
const keyID = process.env.OCSS_SANDBOX_KEY_ID!;
const target = `${BASE}/sandbox/consent-attestations`;
const bodyText = JSON.stringify({ band: "13_15", consent_scope: "collection_parental_authority" });
 
async function mint() {
  const headers = signRequest({
    method: "POST", targetURI: target,
    body: new TextEncoder().encode(bodyText),
    keyID, seed, created: Math.floor(Date.now() / 1000),
  });
  headers["Content-Type"] = "application/json";
  const res = await fetch(target, { method: "POST", headers, body: bodyText });
  return { status: res.status, replay: res.headers.get("ocss-replay"), body: await res.json() };
}
 
console.log(await mint());
console.log(await mint()); // same derived key both times

{
  "ok": true,
  "app_ref": "did:ocss:loopline",
  "target_ref": "child:5ba0d00c-0000-4000-8000-0000000000c1",
  "standing_ref": "consent:attestation:sbx-consent:did:ocss:loopline:child:5ba0d00c-0000-4000-8000-0000000000c1",
  "idempotency_key": "sbx-consent:did:ocss:loopline:child:5ba0d00c-0000-4000-8000-0000000000c1",
  "band": "13_15",
  "consent_scope": "collection_parental_authority",
  "expiry": "2027-07-06T07:02:30Z"
}

The idempotency_key is derived from (caller DID, target child) — no timestamp — so it is identical on every honest retry. Pass the returned target_ref straight into POST /enforcement-endpoints to finish the consent-first mint.

Client-supplied keys

Where an endpoint accepts a client key (rule writes, source syncs), put it in the body and reuse it — with the same payload — on every retry:

BASE=https://phosra-api-sandbox-production.up.railway.app
# Reuse ONE key + the SAME body across retries. First call applies; retries replay.
KEY="rules-2026-07-06-batch-01"
curl -s -X POST "$BASE/api/v1/policies/$POLICY_ID/rules" \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"'"$KEY"'","rule_category":"content_rating","age_band":"13_15","...":"..."}'

On a faithful retry this returns 200 with OCSS-Replay: original and the exact receipt bytes from the first call.

The one pitfall: a changed payload

A 409 replay almost always means a retried request mutated its body between attempts — a regenerated timestamp, a fresh nonce, or a reordered array. The key is frozen to its first payload; a different payload under the same key is rejected.

{
  "error": "Conflict",
  "message": "idempotency key reused with a different payload",
  "code": 409,
  "class": "replay"
}

Retry rules

Next steps