Authenticate as your organisation
Create and revoke records from your own systems, with your organisation as the signer.
Authenticate the documents your organisation issues straight from your systems. Each record is signed with your organisation's own key, committed to the public ledger, and checkable by anyone.
When to use it
| Use the API | Use the portal |
|---|---|
| Documents your organisation issues in volume: statements, certificates, letters | Documents where a named person must be accountable |
| The record shows that your organisation signed | The record names the person, confirmed with their passkey |
A check always shows which of the two stands behind a record, so readers know what they are
relying on. A check made with an organisation key (the organisation tier) also names your
organisation. An anonymous check shows that an organisation signed, without naming it.
Before you start
- Your organisation is validated, and has the organisation authentication add-on.
- You have a key with the
records:writescope. Create it in the portal under Settings → Organisation → API credentials. See API keys. - You call the API from your server, never from a browser.
Authenticate a document
Hash the file on your side, then send the hash. Audrie never receives the document.
curl -sX POST https://api.audrie.io/v1/records \
-H "Authorization: Bearer $AUDRIE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"originalDocHash":"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}'You get back a recordId and a verifyUrl that anyone can open. A first call returns 201. Repeat
the call for the same hash and you get 200 with the same record, so retrying after a timeout
never creates a duplicate.
The ledger entry settles within a few seconds. To confirm it, verify the same hash as usual:
| The answer | What to do |
|---|---|
no_record | Normal for the first moments. Check again shortly. |
pending_anchor | On the ledger and settling. Wait retryAfterSeconds and check again. |
verified_org | Done. With a test key you see sandbox instead. |
Still no_record after about 3 minutes | The anchor did not complete. Call POST /v1/records again for the same hash and a new record is created. |
pending_anchor for many minutes | Report it with the recordId. Authenticating again will not help. |
An optional filename is shown on the public verification page. Leave out anything confidential,
such as client names or matter references.
Revoke a record
Revoke a record your organisation authenticated when it is superseded or wrong:
curl -sX POST https://api.audrie.io/v1/records/$RECORD_ID/revoke \
-H "Authorization: Bearer $AUDRIE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"SUPERSEDED"}'This needs a key created with records:revoke. Revocation is permanent and the record stays
visible, with the reason, so anyone checking it sees what happened. A corrected document is a new
document: authenticate the new one and revoke the old one as superseded.
If something goes wrong
| You see | What to do |
|---|---|
402 | API access or the organisation authentication add-on is not enabled. Your key is fine. |
403 with ORG_NOT_VALIDATED | Wait for validation to complete. Verification keeps working. |
403 with FORBIDDEN | Read error.message. The key may lack the scope, the call may come from a browser, or the record is not one your organisation can revoke. |
409 | The record is already revoked, or its entry has not settled yet. Verify its hash: revoked means you are done, otherwise retry once it reports verified_org. |
503 | Retry a few times with backoff, then report it. Do not rotate your key. |
Every status and code is in Errors.