VachanSetu

Developer guide

This guide takes a backend developer from a sandbox account to a first consent, a first decision check and a verified webhook.

VachanSetu is a consent management platform. It is not a registered Consent Manager under Section 6 of the Act.

Every path on this page is relative to the API base https://vachansetu.in/api/v1, written out in full in the examples.

From sign-up to your first decision

Four steps in the sandbox. All values here are samples.

  1. Create a sandbox and an API client

    Sign up for the sandbox, then open Developers and create an API client. You receive a client id and a secret. Store the secret in your secret manager.

  2. Get an access token

    Server systems use OAuth 2 client credentials. The token lasts 15 minutes. Request a new one when it expires.

    Request
    curl -s -X POST https://vachansetu.in/api/v1/oauth/token \
      -d grant_type=client_credentials \
      -d client_id=YOUR_CLIENT_ID \
      -d client_secret=YOUR_CLIENT_SECRET
    Response
    {
      "access_token": "eyJhbGciOiJFZERTQSJ9...",
      "token_type": "Bearer",
      "expires_in": 900,
      "scope": "consents:write decisions:read"
    }
  3. Record a consent

    Send the person's id in your system, the notice and the choice for each purpose. The Idempotency-Key header is required. Resend the same key after a network error and the person is recorded once. A purpose with granted: false is stored as a refusal.

    Request
    curl -s -X POST https://vachansetu.in/api/v1/consents \
      -H "Authorization: Bearer $TOKEN" \
      -H "Idempotency-Key: 7d0c5a1e-3b52-4c1e-9a6e-2f4d8b9a0c11" \
      -H "Content-Type: application/json" \
      -d '{
        "subject_id": "cust_48213",
        "notice": { "slug": "marketing-consent" },
        "language": "en",
        "channel": "api",
        "purposes": [
          { "key": "partner_offers", "granted": true },
          { "key": "order_updates", "granted": false }
        ]
      }'

    The response is a receipt. proof reads { "pending": true } until the event is sealed into a block, normally within a minute.

    Response, shortened
    {
      "artefact": {
        "v": 1,
        "artefact_id": "0b1c2d3e-0000-4000-8000-000000000001",
        "event_id": "1a2b3c4d-0000-4000-8000-000000000001",
        "event_type": "granted",
        "tenant": "Zm9ydHk0Mm5vdGFSZWFsS2V5",
        "principal_ref": "p_Qm9yb3dlZEZyb21BbkV4YQ",
        "purposes": [
          { "key": "order_updates", "purpose_version": 1, "state": "withdrawn" },
          { "key": "partner_offers", "purpose_version": 1, "state": "granted" }
        ],
        "notice": { "slug": "marketing-consent", "version": 1, "sha256": "2a0ccb3b..." },
        "language": "en",
        "channel": "api",
        "guardian_ref": null,
        "supersedes": null,
        "occurred_at": "2026-11-20T10:01:00.000Z"
      },
      "canonical": "eyJhcnRlZmFjdF9pZCI6...",
      "signature": "+8sguvsOyxA...",
      "key_id": "vs-Zm9ydHk0Mm5vdGFSZWFsS2V5-1",
      "public_key_url": "https://vachansetu.in/api/v1/keys/Zm9ydHk0Mm5vdGFSZWFsS2V5",
      "proof": { "pending": true }
    }
  4. Check a decision before you process

    Call POST /api/v1/decisions before processing. The token needs the decisions:read scope.

    Request
    curl -s -X POST https://vachansetu.in/api/v1/decisions \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "subject_id": "cust_48213",
        "purpose": "partner_offers",
        "system": "campaign-sender"
      }'
    Response
    {
      "decision": "allow",
      "basis": "consent",
      "reason": "granted",
      "artefact_id": "0b1c2d3e-0000-4000-8000-000000000001",
      "notice_version": 1,
      "checked_at": "2026-11-20T10:02:31.402Z",
      "decision_id": "5e2f0c7a-7a0e-4c55-b0e3-9d3a1f7c4a10"
    }

API reference

Base: https://vachansetu.in/api. Requests and responses are JSON. Generated from the OpenAPI 3.1 file, version 1.

The machine-readable file is openapi-v1.yaml. The preference center's own routes under /v1/pc serve the hosted page and are not part of this contract.

Method and pathAuthWhat it does
POST /v1/oauth/tokenNoneSwap an API client for a 15-minute access token
POST /v1/consentsBearer consents:write or Publishable keyRecord a consent choice
POST /v1/consents/{artefactId}/withdrawBearer consents:write or Publishable keyWithdraw a consent
GET /v1/principals/{subjectId}/consentsBearer consents:readCurrent state of each purpose for one person
POST /v1/principals/{subjectId}/session-linksBearer consents:writeMint a single-use link into the person's preference center
GET /v1/artefacts/{id}/receiptBearer consents:readFetch the receipt for an artefact
POST /v1/subject-tokensBearer consents:writeMint a 10-minute subject token for a browser
POST /v1/decisionsBearer decisions:readCheck whether processing is allowed
POST /v1/rights-requestsBearer requests:writeRaise a request on behalf of a person
GET /v1/rights-requests/{slug}Bearer requests:writeStatus of a request
GET /v1/assurance/summaryBearer assurance:readAggregate consent figures for compliance tooling
GET /v1/notices/{tenantKey}/{noticeSlug}NoneThe published notice
GET /v1/widget.jsNoneThe collection widget
GET /v1/widget.{hash}.jsNoneThe content-hashed widget file
GET /v1/keys/{tenantKey}NoneA tenant's public signing keys
GET /v1/verify/keys/{tenantKey}NoneA tenant's public signing keys, under the verification prefix
GET /v1/verify/blocks/{tenantKey}/{n}NoneA sealed block of the tenant's ledger
GET /v1/verify/anchors/{id}NoneA time-stamped anchor
GET /v1/verify/artefacts/{id}/proofNoneThe proof bundle for one artefact
  • Every write that records a consent event takes an Idempotency-Key.
  • Rate limits apply per client and per IP address.
  • Request bodies are capped at 64 KiB. Batch decisions may be 1 MiB.
  • An error carries a VachanSetu code with the HTTP status.
  • A publishable key, bound to the origins you allow, can call only the two consent write routes.

Authentication

Server credentials and browser tokens.

Swap an API client for a 15-minute access token

POST /api/v1/oauth/token

Auth: None

OAuth 2 client credentials. Send client_id and client_secret in the body, or as HTTP Basic credentials. Omit scope to receive every scope the client holds. The token is an EdDSA-signed bearer token and lasts 900 seconds. The response is never cached.

Request body

NameTypeNotes
grant_type (required)client_credentials
client_idstring
client_secretstring
scopestringSpace-separated scopes. Omit for all of the client's scopes.

Responses

  • 200 A bearer token.
  • 400 The request is not valid.
  • 401 The credentials or token are missing, not valid or expired.
  • 429 Too many requests.

Mint a 10-minute subject token for a browser

POST /api/v1/subject-tokens

Auth: Bearer consents:write

Your server calls this for the signed-in person and gives the token to the page. The widget sends it as subject_token, so the browser never chooses whose consent it records.

Request body

NameTypeNotes
subject_id (required)stringYour identifier for the person. No control characters.

Responses

  • 201 The token.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 422 A field is missing or not valid.

Consents

Record, read and withdraw consent.

Record a consent choice

POST /api/v1/consents

Auth: Bearer consents:write or Publishable key

Records the person's choice for each purpose of a published notice. A purpose with granted: false is stored as a refusal. Name the person with subject_id (your own identifier for them) or with a subject_token minted by your server. A browser using a publishable key may send a plain subject_id only when the tenant allows it, which is on by default in the sandbox and off when live.

The response is a receipt. proof reads { "pending": true } until the event is sealed into a block. If the person's email is given and at least one purpose is granted, an emailed receipt is sent when the tenant has turned that on.

Parameters

NameTypeNotes
Idempotency-Key (header) (required)string1 to 120 characters of A-Z a-z 0-9 . _ : -.

Request body

NameTypeNotes
subject_idstringYour identifier for the person. No control characters.
subject_tokenstringFrom POST /v1/subject-tokens. Send this or subject_id, not both.
identityobjectOptional contact details, each up to 200 characters. Used for the emailed receipt.
notice (required)object
language (required)string
channelstringDefaults to api for a bearer token and web for a publishable key.
purposes (required)object[]

Responses

  • 200 The same Idempotency-Key was used before. The first receipt is returned.
  • 201 Recorded. The body is the receipt.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 422 A field is missing or not valid.
  • 429 Too many requests.

Withdraw a consent

POST /api/v1/consents/{artefactId}/withdraw

Auth: Bearer consents:write or Publishable key

Records a withdrawal of the consent in the named artefact. Omit purposes to withdraw every purpose that is still granted, or list the purpose keys to withdraw. The response is the receipt of the withdrawal. Withdrawing something already withdrawn answers 409.

Parameters

NameTypeNotes
artefactId (path) (required)string
Idempotency-Key (header) (required)string1 to 120 characters of A-Z a-z 0-9 . _ : -.

Request body

NameTypeNotes
subject_idstringYour identifier for the person. No control characters.
subject_tokenstring
purposesstring[]
channelstring

Responses

  • 200 The same Idempotency-Key was used before. The first receipt is returned.
  • 201 Recorded. The body is the receipt.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 Not found.
  • 409 Every named purpose is already withdrawn (vachansetu.consent.already_withdrawn).
  • 422 A field is missing or not valid.
  • 429 Too many requests.

Current state of each purpose for one person

GET /api/v1/principals/{subjectId}/consents

Auth: Bearer consents:read

Returns the latest state of every purpose the person has a record for, with the artefact and notice version behind it. Add ref=1 to pass a principal_ref (from a receipt or webhook) instead of your own subject id.

Parameters

NameTypeNotes
subjectId (path) (required)stringYour identifier for the person, or a principal_ref when ref=1.
ref (query)1

Responses

  • 200 The person's purpose states.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 No consent records were found for this person (vachansetu.principal.not_found).
  • 422 A field is missing or not valid.
  • 429 Too many requests.

Fetch the receipt for an artefact

GET /api/v1/artefacts/{id}/receipt

Auth: Bearer consents:read

Returns the receipt. proof is { "pending": true } until the event is sealed, then carries the inclusion proof. The format is specified in artefact-v1.md.

Parameters

NameTypeNotes
id (path) (required)string

Responses

  • 200 The receipt.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 Not found.

Decisions

Ask whether processing is allowed.

Check whether processing is allowed

POST /api/v1/decisions

Auth: Bearer decisions:read

Send one check, or { "checks": [ … ] } with 1 to 500 checks, and receive allow or deny for each, with the reason and the artefact it rests on. Each check names the person with exactly one of subject_id and principal_ref. The body may be up to 1 MiB. The response is never cached.

Request body

NameTypeNotes
subject_idstringYour identifier for the person. No control characters.
principal_refstringGive exactly one of subject_id and principal_ref.
purpose (required)string
data_itemsstring[]
systemstringThe system asking, recorded in the decision log.

Responses

  • 200 One result for a single check, or results in request order for a batch.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 Not found.
  • 422 A field is missing or not valid.
  • 429 Too many requests.

Rights requests

Raise and follow requests from the people you hold data about.

Raise a request on behalf of a person

POST /api/v1/rights-requests

Auth: Bearer requests:write

Opens an access, correction, erasure, nomination or grievance request for the person. Correction, erasure, nomination and grievance need details. The response carries the reference and the due date.

Request body

NameTypeNotes
subject_id (required)stringYour identifier for the person. No control characters.
type (required)access | correction | erasure | nomination | grievance
detailsstringPlain text.
channel_notestringHow the request reached you, for your own records.

Responses

  • 201 The request.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 Not found.
  • 422 A field is missing or not valid.

Status of a request

GET /api/v1/rights-requests/{slug}

Auth: Bearer requests:write

Returns the status, the due date and the messages meant for the person. Internal notes are never returned.

Parameters

NameTypeNotes
slug (path) (required)stringThe request reference, for example RR-261120-0001.

Responses

  • 200 The request.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 Not found.

Notices and widget

Public, cacheable resources for the collection widget.

The published notice

GET /api/v1/notices/{tenantKey}/{noticeSlug}

Auth: None

Returns the current published version of a notice in the requested language, with the tenant's display name and branding. Public and cacheable for 60 seconds, with an ETag. Answers 304 when If-None-Match matches.

Parameters

NameTypeNotes
tenantKey (path) (required)stringThe tenant key, 24 characters of A-Za-z0-9_-.
noticeSlug (path) (required)string
lang (query)stringTwo-letter language code. The notice's default language is used when this one is not published.

Responses

  • 200 The notice.
  • 304 Not modified.
  • 404 Not found.

The collection widget

GET /api/v1/widget.js

Auth: None

Redirects (302) to the immutable, content-hashed file /v1/widget.{hash}.js. Allowed for any origin.

Responses

  • 302 Redirect to the hashed file.
  • 404 Not found.

The content-hashed widget file

GET /api/v1/widget.{hash}.js

Auth: None

JavaScript. Cached for a year as immutable. An old hash answers 404.

Parameters

NameTypeNotes
hash (path) (required)string

Responses

  • 200 The widget bundle.
  • 404 Not found.

Verification

Public routes a verifier uses. No authentication.

A tenant's public signing keys

GET /api/v1/keys/{tenantKey}

Auth: None

Every key the tenant has signed with, each with its validity period. Public, cacheable for 60 seconds, allowed for any origin.

Parameters

NameTypeNotes
tenantKey (path) (required)stringThe tenant key, 24 characters of A-Za-z0-9_-.

Responses

  • 200 The keys.
  • 404 Not found.

A tenant's public signing keys, under the verification prefix

GET /api/v1/verify/keys/{tenantKey}

Auth: None

The same body as /v1/keys/{tenantKey}.

Parameters

NameTypeNotes
tenantKey (path) (required)stringThe tenant key, 24 characters of A-Za-z0-9_-.

Responses

  • 200 The keys.
  • 404 Not found.

A sealed block of the tenant's ledger

GET /api/v1/verify/blocks/{tenantKey}/{n}

Auth: None

The signed header bytes, the header as JSON, the signature and the block hash. When the block has been anchored, anchor holds the leaf index, tree size, audit path and the time-stamped root.

Parameters

NameTypeNotes
tenantKey (path) (required)stringThe tenant key, 24 characters of A-Za-z0-9_-.
n (path) (required)integerBlock number, from 1.

Responses

  • 200 The block.
  • 404 Not found.

A time-stamped anchor

GET /api/v1/verify/anchors/{id}

Auth: None

The Merkle root over a set of blocks, the number of leaves, the RFC 3161 time-stamp response (base64 DER) and the time it states. others lists tokens from any further time-stamp authority. Immutable.

Parameters

NameTypeNotes
id (path) (required)integer

Responses

  • 200 The anchor.
  • 404 Not found.

The proof bundle for one artefact

GET /api/v1/verify/artefacts/{id}/proof

Auth: None

The receipt body without the proof token: the artefact, its canonical bytes, the signature, the key id and the block and anchor inclusion proofs. It needs the receipt's proof_token, in token or in the X-VS-Proof-Token header. A missing or wrong token answers the same 404 as an unknown id, so artefact ids cannot be probed. Never cached.

Parameters

NameTypeNotes
id (path) (required)string
token (query)string
X-VS-Proof-Token (header)string

Responses

  • 200 The proof bundle.
  • 404 Not found.

Assurance

Aggregates for compliance tooling.

Aggregate consent figures for compliance tooling

GET /api/v1/assurance/summary

Auth: Bearer assurance:read

Counts only. The response never contains a principal reference or a subject identifier. as_of takes an ISO 8601 date or time and is capped at now.

Parameters

NameTypeNotes
as_of (query)string

Responses

  • 200 The aggregates. The members are defined by the tenant's assurance summary and may grow.
  • 401 The credentials or token are missing, not valid or expired.
  • 403 The credential lacks the scope, or the origin is not allowed for the key.
  • 404 Not found.
  • 422 A field is missing or not valid.

The collection widget

One script of about 8 KB gzipped. It has no dependencies and draws inside a shadow root, so your page's CSS cannot break it.

Embed
<script>
  window.VachanSetu = window.VachanSetu || { q: [], onReady: function (f) { this.q.push(f); } };
</script>
<script src="https://vachansetu.in/api/v1/widget.js" defer></script>

<div id="consent"
     data-vs-notice="marketing-consent"
     data-vs-tenant="YOUR_TENANT_KEY"
     data-vs-key="YOUR_PUBLISHABLE_KEY"></div>

<script>
  VachanSetu.onReady(function (w) {
    w.mount('#consent', {
      subjectId: 'cust_48213',
      language: 'en',
      onResult: function (r) { console.log(r); }
    });
  });
</script>

What it renders

It shows your published notice in the person's language, open by default.

It shows one unticked box for each purpose that rests on consent. Purposes that rest on a Section 7 basis are listed as information.

Two buttons of equal weight sit below: “I agree to the selected purposes” and “Decline all”. Either one records every consent purpose, so a refusal is evidence too.

The choice goes to POST /api/v1/consents with your publishable key and a fresh idempotency key. The person then gets a link to their preference center.

Languages: en, hi, ta, te and kn. Theme it with the CSS variables --vs-accent, --vs-radius and --vs-font.

A subject id set in a browser can be spoofed

Anyone who can open your page can change the id in their developer tools and record a consent for another customer id. Treat browser-recorded consent as a convenience record. It does not prove who the person is.

For a stronger binding, mint a subject token on your server and pass it as subjectToken instead of subjectId. The token is valid for 10 minutes, works only for your tenant, and is never accepted as an access token. A plain subject id from a browser is accepted while the tenant is a sandbox. A live tenant can turn it off.

Subject token
curl -s -X POST https://vachansetu.in/api/v1/subject-tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "subject_id": "cust_48213" }'

# 201
{ "subject_token": "...", "expires_at": "2026-11-20T10:10:00.000Z" }

Decisions

Call the decision endpoint before you process personal data for a purpose. Honour the answer.

Request

Send subject_id or principal_ref, and a purpose key. Optional:data_items, a list of data item keys that must all belong to the purpose, and system, a label for the caller that appears in the decision log.

Response

decision is allow or deny. basis is consent, a Section 7 basis that starts with s7_, or null. The response also carries artefact_id, notice_version, checked_at and a decision_id.

A purpose with a Section 7 basis answers allow without a consent. A purpose that rests on consent answers allow only while the consent is granted.

Batches

Send { "checks": [...] } with up to 500 checks. You get one answer for each.

Every check is logged

Each answer is written to the decision log with the person, purpose, result, reason, system and client. You can search it by person, purpose, result and time.

Batch request
{
  "checks": [
    { "subject_id": "cust_48213", "purpose": "partner_offers" },
    { "subject_id": "cust_48214", "purpose": "partner_offers" }
  ]
}
reasonMeaning
grantedA consent is on record and has not been withdrawn.
withdrawnThe person withdrew it.
expiredThe consent passed its validity.
no_consentNothing is on record. An unknown subject gets this answer, and no person record is created.
unknown_purposeThe purpose key does not exist in your inventory.
data_item_not_in_purposeYou listed a data item that is not linked to the purpose.
principal_erasedThe person has been erased.

Webhooks

A signed HTTPS POST tells your system within seconds that a consent changed.

Register an endpoint in Developers, pick the events, and copy the signing secret. It starts with whsec_ and is shown once. The address must be https. The sandbox also accepts http. Addresses that resolve to private or non-public ranges are refused, and redirects are not followed.

EventSent when
consent.grantedA consent record with at least one granted purpose is sealed.
consent.modifiedA person changes an earlier consent.
consent.withdrawnA withdrawal is recorded. purposes lists what was withdrawn.
consent.expiredA consent passes its validity.
rights_request.openedA person opens an access, correction, erasure or grievance request.
rights_request.closedThe request is closed.
erasure.requestedAn erasure request is accepted.
notice.version_publishedA notice version is published.
pingYou pressed Send test.

You can subscribe to consent.expired, rights_request.* and erasure.requested now. Their senders arrive in a later release.

The data object never holds a person's identifier, name, e-mail or phone number. It holds a principal_ref. Resolve it with GET /api/v1/principals/{ref}/consents?ref=1.

One delivery
POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: VachanSetu-Webhooks/1
VS-Webhook-Id: 6f1f2d3a-8c52-4a0e-9e0b-0d1d2f6b6a11
VS-Webhook-Timestamp: 1763645709
VS-Signature: v1=3c9f...e1

{"id":"6f1f2d3a-8c52-4a0e-9e0b-0d1d2f6b6a11","type":"consent.withdrawn","created_at":"2026-11-20T13:25:09.679Z","tenant":"Zm9ydHk0Mm5vdGFSZWFsS2V5","data":{...}}

Verify the signature

Three headers come with every request.

  • VS-Webhook-Id: the event id. It is the same on every retry. Use it to deduplicate.
  • VS-Webhook-Timestamp: Unix seconds at which this attempt was signed.
  • VS-Signature: v1= followed by the lower-case hex of HMAC-SHA256(secret, timestamp + "." + body).

Use the raw body exactly as received. Reject a timestamp more than 5 minutes from your clock. Compare in constant time. Answer with a 2xx within 10 seconds, then do the slow work.

Test vector: secret whsec_test_secret, timestamp 1700000000, body {"id":"evt_1","type":"ping"} gives v1=74a11abdd08483d064a2a1571e7881b084c522f9f3ccd0b800ec8c74aba47fc2.

Node
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, rawBody, headers, toleranceSeconds = 300) {
  const ts = headers['vs-webhook-timestamp'];
  const sig = headers['vs-signature'] ?? '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds) return false;
  const expected = 'v1=' + createHmac('sha256', secret).update(`${ts}.`).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(sig);
  return a.length === b.length && timingSafeEqual(a, b);
}

Retries

A 2xx answer acknowledges the event. Any other status, a timeout or a connection error is a failed attempt. VachanSetu retries on this schedule, measured from the failed attempt.

After attemptNext step
130 seconds
22 minutes
310 minutes
430 minutes
51 hour
62 hours
74 hours
88 hours
9The delivery is marked dead

That is one attempt and eight retries over about 15 hours 40 minutes. Each attempt is stored with its status code, latency and the first 1 KiB of your answer. A dead delivery stays visible and can be sent again with Redeliver. An endpoint whose last 50 deliveries were all dead is disabled until you enable it again.

Delivery is at least once. A retried event can arrive after a later one, so order by created_at or data.seq.

The consent artefact

One artefact is one event: a consent given, changed or withdrawn. It is a JSON object with exactly these members.

MemberTypeRule
vintegerAlways 1.
artefact_idstringUUID, unique per event. The handle a receipt and a withdrawal refer to.
event_idstringUUID, the ledger's own identity for the event.
event_typestringgranted, withdrawn or modified.
tenantstringYour tenant key: 24 URL-safe characters. Public keys are published under it.
principal_refstringp_ followed by 22 characters. A random pseudonym that cannot be reversed to the person's own identifier.
purposesarrayOne entry per purpose, sorted by key. Each is key, purpose_version and state (granted or withdrawn). Refusals are kept as withdrawn states.
noticeobjectslug, version and sha256: the hash of the notice content as it was shown.
languagestringISO 639-1 code of the language the notice was shown in.
channelstringWhere the event was captured, such as web, api or preference_center.
guardian_refnullAlways null in version 1. Reserved for a guardian.
supersedesstring or nullThe artefact this event changes or withdraws. Null for a first grant.
occurred_atstringUTC, YYYY-MM-DDTHH:MM:SS.sssZ, always three fractional digits.

Only integers, strings and null occur. Unknown members are not allowed in version 1.

The canonical bytes are the artefact serialised with RFC 8785 JSON Canonicalization, as UTF-8. The artefact_hash is the SHA-256 of those bytes. The signature is a pure Ed25519 signature over the bytes themselves, not over the hash. The event's Merkle leaf is SHA-256(0x00 || canonical bytes).

Events are sealed into signed blocks that name the hash of the block before them. A verifier needs only the bytes, the signature and the public key.

How verification works

Verify a receipt

Anyone holding a receipt can check it without trusting our database.

Where the pieces are

Public keys need no authentication: GET /api/v1/keys/{tenant_key}. Each key has a key_id, a base64 and hex public key, and a validity window. Rotation adds a key and never re-signs old events, so old receipts keep verifying.

Your own systems fetch a receipt with GET /api/v1/artefacts/{artefact_id}/receipt. It returns the artefact, canonical bytes, signature, key id, key URL and the inclusion proof. Until the event is sealed, the proof reads pending.

To check a receipt, confirm the signature over the canonical bytes, rebuild the Merkle root from the audit path, then confirm the block header carries that root and is signed by the same key.

The vachansetu-verify command-line tool does these checks for you. It imports none of our code and needs no connection for an evidence pack. It is released with the production service.

Verifier commands
# a receipt, checked against the public routes
vachansetu-verify receipt receipt.json --online --base https://vachansetu.in/api/v1

# an evidence pack, checked offline against a time-stamp root you trust
vachansetu-verify pack evidence.zip --tsa-root tsa-root.pem

Exit code 0 means everything verified, 1 means a check failed and the output names the file and the reason, and 2 means part could not be checked, for example when no trusted time-stamp root was given.

What a valid receipt proves

It proves that the tenant's signing key signed exactly these bytes. It proves they are a leaf of a signed block, and that the block belongs to one unbroken chain.

What it does not prove

It does not prove the person's identity. The ledger holds a pseudonym. Identifying details are kept encrypted, apart from it.

Erasing a person deletes the key that decrypts those details. The artefacts and blocks are untouched, so every receipt and block signature still verifies. Every hour, block roots are time-stamped by an RFC 3161 authority.

Try the verifier on the worked example

Start in the sandbox.

The sandbox is free and runs in test mode. Build your purpose inventory, publish a notice and record a first consent before you speak to anyone.