Skip to content

ConsentAlly works with AI assistants. A merchant can have their assistant set up, sign in to or check their ConsentAlly account from the chat: the assistant needs only the merchant's email address, and the merchant approves it on one ConsentAlly page with a code. Nothing is created or connected before that approval. How it works: https://consentally.com/auth.md

Docs pages

Verify a consent record

A consent record in ConsentAlly can be checked by anyone who holds your export, without our dashboard and without taking our word for it. Each record carries the SHA-256 hash of its own fields and the hash of the record before it, so a record that is changed, removed or put out of order breaks the chain from that record on. Once a day ConsentAlly signs a checkpoint of every store's latest record with Ed25519. This page shows how to check both with a short Node.js script.

What you need

  • Your export. Download a CSV from Insights or Records, or the full export from your store's settings. Every row carries every field its hash covers and its place in the chain. Use the file exactly as downloaded: a spreadsheet that opens and saves it can change a value.
  • A signed checkpoint. Open the record in the dashboard: it names the day of the signed daily proof that covers it. Write to support@consentally.com with that date and support sends that day's checkpoint as two files, exactly as stored: the checkpoint and its signature. Your export has to reach that day, so export a range from the record's day through the checkpoint's day, or use the full export.
  • The public key. The keys that sign checkpoints are published at consentally.com/.well-known/checkpoint-keys.json, written from the same list the signing service checks its key against on every build of this site.
Checkpoint signing keys, also at /.well-known/checkpoint-keys.json
Key IDAlgorithmSigns checkpoints datedPublic key (JWK x)
2026-10Ed25519From 2026-10-13x7ivdWD3wS4RDTSbSNlRalF_nFkgE-SvZ6UXbw5mPs8

What the chain fields mean

The export's columns after gpc are the ones that make a record checkable:
The chain fields in the consent records export
ColumnWhat it holds
store_idYour store's ID. Checkpoints name each store by it.
seqThe record's place in your store's chain: 1 for the first record, then one more for each.
record_idThe record's own ID, inside its hash so two records cannot swap places.
nonceThe widget's random ID for the event, inside the hash.
client_decided_at_utcWhen the visitor's browser says the choice was made. The record's time is `received_at_utc`.
prev_hashThe `hash` of the record before it. The first record's is 64 zeros.
hashSHA-256 of the record's canonical text, in lowercase hex.

Recompute a record's hash

A record's hash is the SHA-256 of one line of JSON, its canonical text, written from the row with no spaces and its keys in this order: categories, clientDecidedAt, configVersion, consentId, country, deviceClass, gpc, id, jurisdiction, method, nonce, prevHash, receivedAt, region, seq, storeId, v, vendors.

  • categories and vendors are objects of true (granted) and false (refused), keys in alphabetical order: analytics:granted;marketing:refused is {"analytics":true,"marketing":false}, and an empty cell is {}.
  • receivedAt is received_at_utc in milliseconds since 1970, clientDecidedAt is client_decided_at_utc in seconds. configVersion is banner_version, deviceClass is device, id is record_id.
  • An empty country or region is null. seq, the version and the times are plain numbers, gpc is true or false, and v is always 1.

This row of an export:

Text
90643823-3ba7-4b92-ba06-f163e9b5ba7f,2026-10-22T11:02:51.004Z,chose_categories,analytics:refused;functional:granted;marketing:refused;necessary:granted,,2,gdpr_eprivacy,DE,,mobile,banner,false,d629ad41-7cdb-4019-90fa-c52afab85588,2,2e34fb9c-42e2-48c7-a615-dec68748142c,1f1b78aa404c0d12e340cdc7665851b6,2026-10-22T11:02:50.000Z,e8d878236c2225dc71359fe010e1ac7b80d323238921178799054528796839ca,88a1df946d46eccb3e152d2ffd773a000b2ab2e543f92b35ac84a0dd4d882e12

has this canonical text, whose SHA-256 is the row's hash, 88a1df94...4d882e12:

JSON
{"categories":{"analytics":false,"functional":true,"marketing":false,"necessary":true},"clientDecidedAt":1792666970,"configVersion":2,"consentId":"90643823-3ba7-4b92-ba06-f163e9b5ba7f","country":"DE","deviceClass":"mobile","gpc":false,"id":"2e34fb9c-42e2-48c7-a615-dec68748142c","jurisdiction":"gdpr_eprivacy","method":"banner","nonce":"1f1b78aa404c0d12e340cdc7665851b6","prevHash":"e8d878236c2225dc71359fe010e1ac7b80d323238921178799054528796839ca","receivedAt":1792666971004,"region":null,"seq":2,"storeId":"d629ad41-7cdb-4019-90fa-c52afab85588","v":1,"vendors":{}}

Check the chain

Sort the rows by seq. From your record on, each row's prev_hash is the hash of the row before it and its seq is one more. A range export starts part way along the chain, so its first row points to a record outside the range; that is expected. When your plan's retention removes old records, it removes them from the start of the chain, so the records kept still link to each other.

Check the signed checkpoint

The checkpoint is one line of JSON, {"builtAt":...,"date":...,"heads":[...],"keyId":...,"prev":...,"v":1}. heads lists every store's latest record when it was built, as {"hash","seq","storeId"}. A checkpoint that re-anchors a chain is format 2, with one more key, below. The signature file is {"keyId":...,"sig":...,"v":1}: sig is the Ed25519 signature over the checkpoint file's exact bytes, in hex, by the key keyId names.
  1. Check the signature with the published key whose ID is the checkpoint's keyId, and that the checkpoint's date falls inside the dates that key signs.
  2. Find your store_id in heads. The row of your export with that seq must have that hash, and the chain from your record must reach it.

When both hold, your record was stored exactly as it is now before the checkpoint was signed. Each checkpoint's prev is the SHA-256 of the checkpoint before it, and the checkpoints are kept for four years in storage that refuses changes and deletion.

When a chain was re-anchored

If ConsentAlly's database is ever restored from a backup, the records stored between the backup and the restore are lost, and a store's chain no longer reaches the head an earlier checkpoint signed. The break is stated, not hidden: staff record a re-anchor naming the store, the signed head given up, the latest signed head the chain still holds and the reason, and the next daily checkpoint signs it.

That checkpoint is format 2: format 1 with one more key, reanchors, between prev and v, and "v":2. It holds one entry per re-anchored store, {"fromHash","fromSeq","id","keptHash","keptSeq","storeId"}:

  • keptSeq and keptHash are the latest head an earlier checkpoint signed that the chain still holds (0 and 64 zeros when none). The store's head in this checkpoint was checked record by record from there.
  • fromSeq and fromHash are the head the previous checkpoint signed, which the chain no longer reaches.

This checkpoint gives up the earlier checkpoints' coverage of the records after keptSeq and checks the chain again from the kept head. Records the restore kept are covered again by it; records it lost are not in the chain, and records stored after the restore continue from the last one kept, so they can reuse lost sequence numbers. For your records this means:

  • A record up to keptSeq is unaffected: the earlier checkpoints still cover it, and so do the later ones.
  • A record after keptSeq in your export now is checked against the re-anchoring checkpoint or a later one, never an earlier one.
  • A record from inside the gap, signed by an earlier checkpoint after keptSeq and lost in the restore, is not in your export and cannot be verified against the chain or any later checkpoint.

A script that checks all of it

Save this as verify-record.mjs and run it with Node.js 20 or later, giving it the export, the visitor's consent ID, the checkpoint, its signature and the keys file:

JavaScript
// node verify-record.mjs <export.csv> <consent ID> <checkpoint.json> <checkpoint.sig> <keys.json>import { createHash, createPublicKey, verify } from "node:crypto";import { readFileSync } from "node:fs"; const [csvFile, consentId, checkpointFile, sigFile, keysFile] = process.argv.slice(2);const read = (file) => readFileSync(file, "utf8"); // 1. The export's rows in chain order. No cell in these columns is ever quoted.const [header, ...lines] = read(csvFile).split("\r\n").filter(Boolean);const names = header.split(",");const rows = lines  .map((line) => Object.fromEntries(line.split(",").map((cell, i) => [names[i], cell])))  .sort((a, b) => Number(a.seq) - Number(b.seq)); // 2. A row's canonical text: keys in this order, no spaces.const map = (cell) => {  const pairs = cell ? cell.split(";").map((pair) => pair.split(":")) : [];  pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));  return `{${pairs.map(([key, word]) => `${JSON.stringify(key)}:${word === "granted"}`).join(",")}}`;};const str = (value) => (value === "" ? "null" : JSON.stringify(value));const canonical = (r) =>  `{"categories":${map(r.categories)},"clientDecidedAt":${Date.parse(r.client_decided_at_utc) / 1000}` +  `,"configVersion":${r.banner_version},"consentId":${str(r.consent_id)},"country":${str(r.country)}` +  `,"deviceClass":${str(r.device)},"gpc":${r.gpc},"id":${str(r.record_id)}` +  `,"jurisdiction":${str(r.jurisdiction)},"method":${str(r.method)},"nonce":${str(r.nonce)}` +  `,"prevHash":${str(r.prev_hash)},"receivedAt":${Date.parse(r.received_at_utc)}` +  `,"region":${str(r.region)},"seq":${r.seq},"storeId":${str(r.store_id)},"v":1` +  `,"vendors":${map(r.vendors)}}`;const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex"); // 3. The record's hash, then every link from it to the end of the export.const start = rows.findIndex((r) => r.consent_id === consentId);if (start === -1) throw new Error("no row with that consent ID");for (let i = start; i < rows.length; i++) {  const r = rows[i];  if (sha256(canonical(r)) !== r.hash) throw new Error(`seq ${r.seq}: the hash does not match`);  const before = rows[i - 1];  if (i > start && (r.prev_hash !== before.hash || Number(r.seq) !== Number(before.seq) + 1))    throw new Error(`seq ${r.seq}: the chain is broken`);}const record = rows[start];console.log(`seq ${record.seq}: hash recomputed, chain intact to seq ${rows.at(-1).seq}`); // 4. The checkpoint's signature, with the published key its keyId names.const text = read(checkpointFile).trimEnd();const { keyId, sig } = JSON.parse(read(sigFile));const checkpoint = JSON.parse(text);if (checkpoint.v !== 1 && checkpoint.v !== 2) throw new Error(`checkpoint format ${checkpoint.v} is unknown`);const key = JSON.parse(read(keysFile)).keys.find((k) => k.keyId === keyId);if (!key || checkpoint.keyId !== keyId) throw new Error(`no published key ${keyId}`);if (checkpoint.date < key.validFrom || (key.validUntil && checkpoint.date > key.validUntil))  throw new Error(`key ${keyId} does not sign checkpoints dated ${checkpoint.date}`);const publicKey = createPublicKey({ key: key.jwk, format: "jwk" });if (!verify(null, Buffer.from(text, "utf8"), publicKey, Buffer.from(sig, "hex")))  throw new Error("the checkpoint's signature does not verify"); // 5. A format 2 checkpoint that re-anchors the store: say whose earlier coverage it gives up.const reanchor = checkpoint.reanchors?.find((r) => r.storeId === record.store_id);if (reanchor)  console.log(    `re-anchored at seq ${reanchor.keptSeq}: earlier coverage of seq ${reanchor.keptSeq + 1}` +      ` to ${reanchor.fromSeq} is given up, and the chain is checked again from seq ${reanchor.keptSeq}`,  ); // 6. The store's head in the checkpoint is a row the chain reached from the record.const head = checkpoint.heads.find((h) => h.storeId === record.store_id);const signed = rows.slice(start).find((r) => Number(r.seq) === head?.seq);if (!signed || signed.hash !== head.hash) throw new Error("the checkpoint does not cover the record");console.log(`signed by key ${keyId} on ${checkpoint.date}: head seq ${head.seq} covers the record`);

With a consent ID that has several records, it starts at the oldest and checks every later one on the way. A good result prints two lines:

Text
seq 2: hash recomputed, chain intact to seq 3signed by key 2026-10 on 2026-10-24: head seq 3 covers the record

Any change to a row, a missing row, a checkpoint that was edited or signed with another key stops it with the reason. When the checkpoint re-anchors your store, a line between the two names the records whose earlier coverage it gives up:

Text
re-anchored at seq 1: earlier coverage of seq 2 to 3 is given up, and the chain is checked again from seq 1

The script then checks your record against the checkpoint's head as usual. A record from inside the gap is not in a current export, so the script stops at "no row with that consent ID"; given an older export that still holds it, it stops at "the checkpoint does not cover the record". The Limitations page lists what ConsentAlly does not do.