AUDRIEDOCS
ReferenceRecords

Revoke a record your organisation authenticated

POST/v1/records/{recordId}/revoke

Marks a record your organisation authenticated as no longer in good standing, and anchors that decision to Hedera.

Revocation is permanent. It cannot be undone, by you or by us. The record is not removed — a Hedera message cannot be withdrawn — and verification continues to report it, with a revoked verdict and the reason you gave.

The credential must carry records:revoke

This scope is granted only when you ask for it as you mint a credential. A credential that can authenticate documents cannot revoke them unless you requested both, and a credential minted without it never gains the scope — mint a new one.

Ask for it on the credentials you intend to revoke with, and not on the ones your batch jobs carry. A credential holding this scope can revoke any record your organisation authenticated, including records created by a different credential. That is what makes it the right tool after a credential is lost: mint a new credential with records:revoke and clean up with it.

A credential granted records:revoke also carries records:write. There is no revoke-only credential, so a key you mint to clean up after an incident can also authenticate documents as your organisation — protect it as a signing key, and revoke it when the cleanup is done.

A test-prefixed credential is never granted this scope.

What you can revoke

Records your organisation authenticated through this API. Documents a person authenticated in the Audrie app are not revocable here — only that signer can revoke those, from the app.

Revoking is not a way to correct a mistake in the document itself. A corrected document is a new document with a new hash: authenticate the new one, and revoke the old one as SUPERSEDED.

Errors

A 403 has two causes, and they read differently. A credential without records:revoke is told so, and the message names the scope. Otherwise the record is not one your organisation can revoke — and that answer deliberately does not distinguish a record belonging to another organisation from one a person authenticated in the Audrie app.

A 409 has two causes and does not distinguish them. Do not retry blindly: if the record is already revoked, retrying never succeeds, because revocation is permanent. If its anchor has not yet reached consensus, retry once POST /v1/verifications reports verified_org. That call is also how you tell the two apart — an already-revoked record reports revoked.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer aud_live_…

Optional on POST /v1/verifications, which answers without any credential. Required to list or read verifications back.

Send exactly one Authorization header. A credential that is present and does not work is refused rather than downgraded to the anonymous tier.

Issue a key in the portal under Settings → Organisation → API credentials; it is shown once, at creation.

Two scopes exist. verifications:read covers every verification operation and is on every key. records:write covers POST /v1/records and is granted only on a live credential whose organisation holds the organisation-issued authentication add-on at the moment the key is minted — a test key never receives it, because there is no sandbox ledger and the records it would create would be permanent — scopes are fixed then and never widen afterwards, because a credential's recorded scopes are what an auditor reads to know what that key could do on a given date. Buying the add-on later means minting a new key; the old one keeps verifying.

Scopes, rotation, revocation, the live and test prefixes and what to do about a leaked key: https://audrie.io/docs/authentication

In: header

Path Parameters

recordId*string

The recordId returned when the document was authenticated. UUID.

Formatuuid

Request Body

application/json

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/records/497f6eca-6276-4993-bfeb-53cbbbba6f08/revoke" \  -H "Content-Type: application/json" \  -d '{    "reason": "SUPERSEDED"  }'
{  "recordId": "9a1b7c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"}

Authenticate a document as your organisation POST

Authenticates a document **as the calling organisation**, signing its hash with the organisation's own post-quantum key and anchoring the result to Hedera. This is the only operation on this API that creates anything. Send a hash. Audrie never receives the document. > **A `test`-prefixed credential cannot reach this operation.** There is > no sandbox ledger: this endpoint signs with your organisation's > production key and anchors a permanent, public Hedera message that > **cannot be withdrawn**, so a key labelled `test` is never granted > `records:write` at all and is refused here with `403`. Mint a `live` > credential when you are ready to create records that are real. ## What this is, and what it is not The signature attributes to an **organisation**, not to a person. No individual is accountable for it: there is no identity-verified signer and no WebAuthn ceremony behind an API call. A verifier sees that difference — these records answer `verified_org` rather than `verified`, carry `signerType: org` on the match, and at the `organisation` tier carry your organisation's registered name in `signerOrg`. Use it where an organisation is the right signer: bulk authentication of documents your organisation issues. Where a named person must be accountable, have that person authenticate in the portal instead. ## Idempotency Retrying is safe, and you do not need an idempotency key: the document hash is the key. Your organisation can hold **one active record per document hash**. A repeat call for a hash you already hold returns that record with `200` and creates nothing; a first call returns `201`. The body is identical either way, because after a timeout you cannot know which call you made — branch on the status only if you care. A record whose anchor ultimately **failed** stops counting, so a later call for that hash creates a new record rather than returning the failed one forever. ## Anchoring is asynchronous, and it can fail On a `201`, `anchorState` is `pending` or `accepted`, and reaches `anchored` at Hedera finality — typically 3–5 seconds. On a `200` retry it is whatever the existing record has already reached, which may be `anchored`. Branch over all three values, not two. Poll `POST /v1/verifications` with the same hash rather than this operation. **Read the verdict, not the clock, and expect three outcomes.** Until the record reaches the ledger, verification answers `no_record` — it reports only records that have been accepted for anchoring, so a record you have just created is briefly invisible there. Then: | The verdict becomes | Meaning | What to do | |---|---|---| | `pending_anchor` | On the ledger, awaiting consensus. | Wait `retryAfterSeconds` and poll again. | | `verified_org` | Anchored. Done. | Nothing. | | still `no_record` after ~3 minutes | **The anchor failed** before the message was submitted. The record is abandoned and stops being active. | Call `POST /v1/records` again for this hash. It will create a new record rather than returning the abandoned one. | | stuck at `pending_anchor` for many minutes | The message reached the ledger but consensus has not been reconciled. **This one does not self-resolve by retrying**, and re-authenticating will not help — the record is still active, so a repeat call returns it unchanged. | Report it with the `recordId`. | **An anchored record cannot be withdrawn.** A Hedera message is permanent. Revocation marks a record as no longer in good standing rather than removing it — see `POST /v1/records/{recordId}/revoke`. ## Errors A `400` means `originalDocHash` is not `sha256:` followed by 64 **lowercase** hex characters, `filename` is longer than 500 characters or contains a control or invisible formatting character, or the body is not a JSON object. `error.details` names the field. Uppercase hex is refused rather than normalised: the hash is used verbatim inside the signature and the ledger message, so two spellings would be two separate permanent records for one document. The `402` and `403` each have more than one cause. **Branch on `error.code`**, and read the response descriptions below — they say which causes exist and which of them mean "wait" rather than "fix something".