Skip to main content

Consent receipts

A receipt is a signed statement that Bytemonk recorded one consent event (a grant or a withdrawal) exactly as described. The person or your company can keep it and check later, without database access, that it has not been altered. It is not a signature by the person and not a qualified electronic signature; how much weight it carries in a dispute is a legal question.

Receipts are switched on for an installation by its administrator (a key-encryption key is configured); where they are off, the calls below answer that receipts are not switched on.

What a receipt contains​

A compact signed token (RS256, type bytemonk-consent-receipt+jws). Its payload says: the receipt reference (jti), the event (GRANT or WITHDRAW) and when, your organisation's public reference, the person as a salted hash (sub), the consent id (CNS-...), the notice code version and language, each purpose with its decision, topic and preference codes, the source (method, capture, surface, website, collection point, preference center), the privacy policy version, the record's checksum and the checksum of its audit entry.

It never contains an IP address, user agent, name, email or phone number. sub is sha256(orgRef + ":" + externalId) where orgRef is the org claim, so you can recompute it for a person you know, and a stranger holding a receipt cannot read who it is about.

Every event gets its own receipt; a receipt is never revoked, so a later withdrawal has its own receipt and the original still says the consent was given at that time.

Get a person's receipts​

GET /consent/records/{id}/receipts (principal token)
GET /api/v1/server/cmp/consent/records/{id}/receipts (Secret key)

Returns the receipts of one consent record, oldest first. If the first one is not there yet it is made now, so asking is never an error because of timing.

{
"entity": [
{ "receiptRef": "rcp_k3m9x2q7ab4d5e", "eventKey": "GRANT", "status": "ISSUED", "kid": "rcp-2026-1", "token": "eyJ...", "issuedAt": "2026-11-11T10:15:00.000+00:00" }
],
"success": true
}

status is PENDING while signing is being retried, ISSUED when done. After the person is erased the stored token is removed and only the reference remains.

Check a receipt offline​

Each installation publishes the public keys it has ever signed with, in the standard JSON Web Key Set format:

GET /.well-known/bytemonk-receipt-keys.json

To verify a token without calling Bytemonk: read the header, require alg RS256 and the typ above, find the key with the header's kid in the key set, check the signature, and only then read the payload. The iss claim names the installation's own address, so the key set is fetched from the installation that issued the receipt. Retired keys stay published so old receipts keep verifying. This tells you the token was signed by that key; it does not tell you the database still agrees (use the online check for that).

Check a receipt online​

GET /api/v1/server/cmp/consent/receipts/{receiptRef}/verify (Secret key)
{
"entity": {
"receiptRef": "rcp_k3m9x2q7ab4d5e",
"status": "ISSUED",
"signatureValid": true,
"issuedByUs": true,
"recordUnchanged": true,
"auditEntryUnchanged": true,
"auditChainOk": true,
"keyStatus": "ACTIVE",
"currentState": "GRANTED",
"reason": null
},
"success": true
}
FieldMeaning
signatureValidThe signature matches the published key
issuedByUsThe token is the one we stored for this reference
recordUnchangedThe consent record's checksum still equals the one in the receipt
auditEntryUnchanged, auditChainOkThe audit entry still has the stated checksum, and your organisation's audit chain verifies
currentStateGRANTED, WITHDRAWN or NONE_GRANTED now, so a later withdrawal is visible
reasonWhy something could not be checked, for example when the audit chain is broken

A receipt of another organisation answers "not found".

Keys​

Administrators see the signing keys (names, status and dates, never key material) and can rotate the key from the dashboard. A new key signs new receipts; retired keys stay published. If a key is thought to be exposed it can be revoked, and offline verifiers should then distrust receipts signed with it after that date; the online check is the stronger defence.