Idempotency

Issuing is idempotent by content

When you issue a credential, Arrota derives its ID from what you sent: your organisation, the recipient, the template, the recipient name, the document type, the issue date, your credential_id and your Idempotency-Key, if any.

If you send the same issuance again, Arrota finds the existing credential and returns 200 with "status": "already_issued" and the original document_id, instead of creating a duplicate. There is no expiry window: the same inputs always return the same credential.

{ "ok": true, "document_id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c", "status": "already_issued" }

Always send issue_date when you might retry

issue_date defaults to today in UTC. A retry that omits it on a different day counts as a new issuance. Send an explicit issue_date on every request you might retry.

The Idempotency-Key header

Idempotency-Key is optional. It becomes part of the credential's identity:

• The same key with the same body returns the original credential.
• A different key with the same body issues a separate credential. Use this when you really do mean to issue two identical credentials.

Arrota does not store keys separately or compare request bodies against them. A key only distinguishes otherwise identical issuances.

Endpoints that are not idempotent

Each accepted POST /api/v1/verifications creates a new verification request and emails the holder. Do not resubmit an accepted request. GET requests change nothing.

Webhooks

Webhook deliveries are at least once, so your receiver should be idempotent too. See Retries and replay.