> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idem0.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Idempotency keys and replay, in two minutes.

## Idempotency keys

An idempotency key is a **stable name for a unit of work**. Same key = same operation. You own the key and idem0 uses it verbatim — it never generates one for you.

Good keys come from something already stable in your system:

* a job id from your queue
* a step id in an agent run
* a hash of the inputs that define the work

Reuse the key on a retry and idem0 knows it's the same call. Use a fresh key when it's genuinely new work.

## Replay

The first call for a key runs for real and idem0 stores the response (encrypted). Every later call with that key **replays** — idem0 returns the stored response byte-for-byte and tags it:

```http theme={null}
idem0-idempotent-replayed: true
```

A replay never hits the model, so it costs **0 credits** and returns immediately. Your retries, resumes, and redeliveries stop double-paying and stop drifting to a different answer.

Replays are available for **30 days** after the first call. After that the record expires and the same key runs fresh again.

## Same key, different request

A key is a promise that the request is the same. If you send the **same key with a different body**, idem0 rejects it with `422 Unprocessable` rather than return the wrong cached answer. Send a key only for the request it belongs to.

If two identical calls race — the same key arrives while the first is still running — the second gets `409 Conflict`. Retry it once the first finishes and you'll get the replay.

## BYOK

idem0 is bring-your-own-key. Your provider token lives in your provider SDK and travels on its normal auth header (`x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI). idem0 forwards it upstream untouched and never stores or logs it. The only credential idem0 owns is your `x-idem0-key`.

## Streaming works too

Streaming responses are idempotent the same way: the first stream is captured as it flows, and a replay re-emits the same stream, tagged `idem0-idempotent-replayed: true`. Use the same key you'd use for a non-streaming call.