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.
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
Name
Type
Notes
grant_type (required)
client_credentials
client_id
string
client_secret
string
scope
string
Space-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
Name
Type
Notes
subject_id (required)
string
Your 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
Name
Type
Notes
Idempotency-Key (header) (required)
string
1 to 120 characters of A-Z a-z 0-9 . _ : -.
Request body
Name
Type
Notes
subject_id
string
Your identifier for the person. No control characters.
subject_token
string
From POST /v1/subject-tokens. Send this or subject_id, not both.
identity
object
Optional contact details, each up to 200 characters. Used for the emailed receipt.
notice (required)
object
language (required)
string
channel
string
Defaults 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
Name
Type
Notes
artefactId (path) (required)
string
Idempotency-Key (header) (required)
string
1 to 120 characters of A-Z a-z 0-9 . _ : -.
Request body
Name
Type
Notes
subject_id
string
Your identifier for the person. No control characters.
subject_token
string
purposes
string[]
channel
string
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
Name
Type
Notes
subjectId (path) (required)
string
Your 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.
Mint a single-use link into the person's preference center
POST /api/v1/principals/{subjectId}/session-links
Auth: Bearer consents:write
Returns a URL that opens the preference center for this person without a sign-in code. The link works once and expires after ten minutes. Answers 404 when the person has no records and 503 when the preference center is not set up for the tenant.
Parameters
Name
Type
Notes
subjectId (path) (required)
string
Responses
201 The link.
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.
503 The preference center is not available (vachansetu.pc.not_configured).
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
Name
Type
Notes
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
Name
Type
Notes
subject_id
string
Your identifier for the person. No control characters.
principal_ref
string
Give exactly one of subject_id and principal_ref.
purpose (required)
string
data_items
string[]
system
string
The 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
Name
Type
Notes
subject_id (required)
string
Your identifier for the person. No control characters.
How 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
Name
Type
Notes
slug (path) (required)
string
The 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
Name
Type
Notes
tenantKey (path) (required)
string
The tenant key, 24 characters of A-Za-z0-9_-.
noticeSlug (path) (required)
string
lang (query)
string
Two-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
Name
Type
Notes
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
Name
Type
Notes
tenantKey (path) (required)
string
The 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
Name
Type
Notes
tenantKey (path) (required)
string
The 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
Name
Type
Notes
tenantKey (path) (required)
string
The tenant key, 24 characters of A-Za-z0-9_-.
n (path) (required)
integer
Block 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
Name
Type
Notes
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
Name
Type
Notes
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
Name
Type
Notes
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.
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.
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.
A consent is on record and has not been withdrawn.
withdrawn
The person withdrew it.
expired
The consent passed its validity.
no_consent
Nothing is on record. An unknown subject gets this answer, and no person record is created.
unknown_purpose
The purpose key does not exist in your inventory.
data_item_not_in_purpose
You listed a data item that is not linked to the purpose.
principal_erased
The 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.
Event
Sent when
consent.granted
A consent record with at least one granted purpose is sealed.
consent.modified
A person changes an earlier consent.
consent.withdrawn
A withdrawal is recorded. purposes lists what was withdrawn.
consent.expired
A consent passes its validity.
rights_request.opened
A person opens an access, correction, erasure or grievance request.
rights_request.closed
The request is closed.
erasure.requested
An erasure request is accepted.
notice.version_published
A notice version is published.
ping
You 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.
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.
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 attempt
Next step
1
30 seconds
2
2 minutes
3
10 minutes
4
30 minutes
5
1 hour
6
2 hours
7
4 hours
8
8 hours
9
The 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.
Member
Type
Rule
v
integer
Always 1.
artefact_id
string
UUID, unique per event. The handle a receipt and a withdrawal refer to.
event_id
string
UUID, the ledger's own identity for the event.
event_type
string
granted, withdrawn or modified.
tenant
string
Your tenant key: 24 URL-safe characters. Public keys are published under it.
principal_ref
string
p_ followed by 22 characters. A random pseudonym that cannot be reversed to the person's own identifier.
purposes
array
One entry per purpose, sorted by key. Each is key, purpose_version and state (granted or withdrawn). Refusals are kept as withdrawn states.
notice
object
slug, version and sha256: the hash of the notice content as it was shown.
language
string
ISO 639-1 code of the language the notice was shown in.
channel
string
Where the event was captured, such as web, api or preference_center.
guardian_ref
null
Always null in version 1. Reserved for a guardian.
supersedes
string or null
The artefact this event changes or withdraws. Null for a first grant.
occurred_at
string
UTC, 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.
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.