Jurisphere Consent · developers
Build consent into your forms and apps.
A script tag for websites, a REST API for everything else, and signed webhooks to keep your systems in step. Every record is data blind: you send your own customer reference, never a name, email or phone number.
See it working on the Acme Finance demo.
Quick start
1. Get a publishable key
In the consent console, open Sites and keys, add your website with its origins (for example
https://www.acme.example), and create a publishable key. Keys are shown once. Publishable keys only work from your allowed origins.2. Add the widget to your pages
HTML<script src="https://jurisphereai.com/consent/v1/widget.js" data-key="pk_live_…" async></script>3. Mark each form that collects personal data
Use the slug of the collection point you created in the console. The widget shows that point's published notice before the form submits.
HTML<form action="/apply" method="post" data-jurisphere-consent="loan-application" data-principal-field="customer_id" data-contact-field="email"> <input name="customer_id" value="CUST-1001" /> <input name="email" type="email" /> <button type="submit">Apply</button> </form> <!-- On submit the widget shows the notice, records the choice, then submits the form with two hidden fields: jurisphere_consent_status and jurisphere_consent_record_id. -->4. Check consent before you use data
From your servers, with a secret key, ask whether a purpose is allowed for a customer right now. Never put a secret key in a browser or app.
Shellcurl -X POST https://jurisphereai.com/api/consent/v1/check \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"principal_ref": "CUST-1001", "purpose": "marketing"}' # {"allowed": true, "basis": "consent", "record_id": "8f3a…", "as_of": "2026-11-11T15:04:05.000+05:30"}
The widget
/consent/v1/widget.js is a single script with no dependencies. It renders in a shadow root, so your page's styles don't leak in, and it fails open: if our service can't be reached, the form still submits and the choice is queued and retried on the next page load.
Modes
| Mode | Use it for | How |
|---|---|---|
| Form mode | Web forms | Add data-jurisphere-consent to the form |
| Direct mode | Single-page apps, custom flows | Jurisphere.consent.request() |
| Cookie mode | Analytics and marketing cookies | data-cookie-mode on the script tag |
Attributes
| Attribute | On | What it does |
|---|---|---|
data-key | script | Your publishable key. Required. |
data-api | script | API origin, if not the script's own origin. |
data-lang | script or form | Preferred notice language, e.g. hi. Defaults to the page's lang. |
data-cookie-mode | script | Show the cookie banner. |
data-jurisphere-consent | form | The collection point slug. |
data-principal-field | form | Name of the field holding your customer reference. |
data-principal-ref | form | The customer reference itself, if it isn't in a field. |
data-contact-field | form | Optional email or phone field. Hashed, so the person can sign in to the preference centre. |
After a choice, form mode submits the form with two hidden fields: jurisphere_consent_status and jurisphere_consent_record_id. If the person cancels, they stay on the form.
Direct mode
const result = await Jurisphere.consent.request({
collectionPoint: "loan-application",
principalRef: "CUST-1001",
language: "hi", // optional; defaults to the page's language
contact: "asha@example.com" // optional; hashed, lets them sign in to the preference centre
});
// result.status: "granted" | "cancelled" | "unavailable" | "error"
// result.record_id, result.purposes: [{ code, granted }]Events
Every outcome is also dispatched as a jurisphere:consent event that bubbles to the document.
document.addEventListener("jurisphere:consent", (e) => {
const { kind, collection_point, status, record_id, purposes, cookies } = e.detail;
// kind: "notice" (a form or request()) or "cookies" (the cookie banner)
});| status | Meaning |
|---|---|
granted | The person chose and the record was saved. |
cancelled | The person closed the notice without choosing. |
unavailable | Our API couldn't be reached. The choice is queued and retried. |
error | Misconfigured: bad key, unknown collection point or a personal identifier as the reference. |
Cookie mode
A banner for analytics and marketing cookies. Nothing is pre-ticked and Reject all is as easy as Accept all. Scripts tagged type="text/plain" with data-consent stay inert until their category is allowed, including scripts a tag manager adds later.
<script src="https://jurisphereai.com/consent/v1/widget.js"
data-key="pk_live_…" data-cookie-mode async></script>
<!-- Held back until the visitor allows the category -->
<script type="text/plain" data-consent="analytics" src="https://example.com/analytics.js"></script>
<script type="text/plain" data-consent="marketing">
loadAdsPixel();
</script>
<button onclick="Jurisphere.consent.cookies.open()">Cookie settings</button>API reference
Base URL: https://<site>/api/consent/v1. All bodies are JSON. The source of truth for every shape below is src/lib/consent/contract.ts; this page explains it.
Keys
Each client site or app (a property) gets two kinds of key, created in the console. A key is shown once; we store only its hash.
| Key | Looks like | Where it's used | Can do |
|---|---|---|---|
| Publishable | pk_live_… / pk_test_… | The browser (widget), mobile apps | Read published notices; record consent; create rights requests. Only from the property's allowed origins. |
| Secret | sk_live_… / sk_test_… | The client's servers only | Everything: change or withdraw consent, check consent, export, create preference links |
Send the key as Authorization: Bearer <key>. Publishable keys are also checked against the request's Origin header.
- Origins. Publishable keys only work from the property's allowed origins (wildcards like
https://*.acme.exampleare allowed). App and offline properties may omitOrigin. - Secret keys never belong in a browser. A secret key sent with an
Originheader is refused with 403. - Revoking a key. A revoked secret key stops working on the next request. A revoked publishable key may keep working for up to 5 seconds on a server that saw it recently.
- CORS. Browsers' preflight requests are only answered with your origin when one of your properties lists it.
- Idempotency. Send
Idempotency-Key: <your id>(oridempotency_keyin the body) on any write:POST /consents,PATCH /consents/{id},POST /consents/{id}/withdraw,POST /requests. A retry with the same key returns the first result.
Errors
{ "error": { "code": "personal_identifier_not_allowed", "message": "principal_ref looks like an email or phone number. Send your own customer reference instead." } }| Code | HTTP | When |
|---|---|---|
bad_request | 400 | Body fails validation (details lists the fields) |
personal_identifier_not_allowed | 400 | principal_ref looks like an email, phone, PAN or Aadhaar |
notice_version_mismatch | 409 | The notice the person saw is no longer the published one; reload it |
unauthorized | 401 | Missing, malformed, unknown or revoked key |
forbidden | 403 | Publishable key used for a secret-only call, or the origin isn't allowed |
not_found | 404 | Unknown collection point, record or request |
conflict | 409 | Same idempotency_key with a different body |
rate_limited | 429 | Over the per-key limit; retry after Retry-After seconds |
internal | 500 | Our fault; safe to retry with the same idempotency_key |
Rate limits: 50 requests/second per key, bursts of 200. /check allows 200/second. Limits are counted on each of our servers separately, so under heavy load you may get somewhat more than this before a 429; don't rely on that headroom. Repeated failed authentication from one client address is also slowed down.
Endpoints
GET /notice?collection_point=<slug>&lang=<code>
Key: publishable or secret.
Returns the published notice in the requested language. If that language isn't reviewed yet, it falls back to the notice's default language. Shape: PublicNotice. Cacheable for 60 seconds.
POST /consents
Key: publishable or secret.
Records a person's choices against the published notice. Shape in: CreateConsentRequest. Shape out: ConsentResponse (record id + artefact).
{
"collection_point": "loan-application",
"principal_ref": "CUST-1001",
"notice_version": 3,
"language": "hi",
"purposes": [
{ "code": "loan_processing", "granted": true },
{ "code": "credit_check", "granted": true },
{ "code": "marketing", "granted": false }
],
"channel": "web",
"page_url": "https://acme.example/apply",
"idempotency_key": "f0b6c1d2-loan-7781"
}Rules:
- Required purposes. All of them must be
granted: trueto create anactiverecord. Otherwise the response is 400 and the widget shows why. - Optional
contact. An email or phone is hashed so the person can later sign in to the preference centre with a one-time code. It is never stored in plain text. page_urlkeeps only the address of the page. Query strings and#fragmentsare dropped, and anything in the path that looks like an email, phone number or PAN is removed, because the consent history can never be edited.- One record per person per collection point. Posting again for the same person and collection point updates that record and adds an
updatedevent.
PATCH /consents/{record_id}
Auth: secret key, or a preference token as Authorization: Preference <token>.
Changes specific purposes. Shape: UpdateConsentRequest. Returns ConsentResponse.
POST /consents/{record_id}/withdraw
Auth: secret key, or a preference token.
Withdraws the listed purposes, or every optional purpose if none are listed. If all purposes end up withdrawn, the record becomes withdrawn. Shape: WithdrawConsentRequest. Returns ConsentResponse.
POST /check
Key: secret.
May this person's data be used for this purpose right now? Shape in: CheckRequest. Shape out: CheckResponse.
{ "allowed": false, "basis": "none", "record_id": "8f3a…", "as_of": "2026-11-11T15:04:05.000+05:30" }A purpose whose lawful basis is a legitimate use (s.7) returns allowed: true, basis: "legitimate_use" without a consent record.
GET /principals/{principal_ref}/consents
Key: secret.
Every record for one person, as artefacts.
GET /export?from=<iso>&to=<iso>&cursor=<c>
Key: secret.
Paginated artefacts plus the raw events with their hashes, for audits. Up to 500 per page.
POST /requests
Auth: publishable key, secret key, or a preference token.
Creates a rights request. Shape in: CreateRightsRequest. Shape out: RightsRequestResponse (reference like JR-7K3Q-2M9X, due date). Deadline: 90 days.
POST /preference-links
Key: secret.
Creates a signed link to the customer's preference centre. Shape in: CreatePreferenceLinkRequest. Shape out: PreferenceLinkResponse. Links expire after at most 7 days.
Links are signed with a per-organisation secret held only on our side, so the only way to get one is to call this endpoint from your server. (Earlier drafts let you sign links yourself with a hash of your secret key; that is no longer accepted, because the same hash is what we store.) A link whose issue time is more than a minute in the future is refused.
Webhooks
Configured in the console per organisation.
Events:
consent.grantedconsent.updatedconsent.withdrawnrequest.createdrequest.updatedrequest.closed
Body: a WebhookEnvelope.
Delivery:
- At least once, in order per record. Deduplicate on
id. - A delivery succeeds when your endpoint answers 2xx within 10 seconds.
- Failed deliveries retry with backoff: 1 minute, 5 minutes, 30 minutes, then 2, 6 and 24 hours.
- After 6 failures in a row the endpoint is paused and the console shows why.
- Endpoint URLs must be
https://on port 443 and resolve only to public addresses; we look the host up before every delivery and don't follow redirects.
Every request carries:
Jurisphere-Signature: t=1794388800,v1=5f2b…Verify it by computing HMAC-SHA256(secret, "<t>.<raw body>") and comparing it to v1 in constant time. Reject anything older than 5 minutes.
import crypto from "node:crypto";
export function verify(secret, rawBody, header) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}HubSpot sync
If the client uses Jurisphere's built-in HubSpot sync, withdrawing a marketing purpose unsubscribes the matching HubSpot contact from email. Contacts are matched on the contact property jurisphere_consent_ref, which must hold the same reference the client sends as principal_ref.
The consent artefact
Every record is returned as a ConsentArtefact (schema https://jurisphere.ai/schemas/consent-artefact/1.0). It contains:
- who the data fiduciary is
- the person's reference (never their contact details)
- where consent was collected
- the exact notice version, language and content hash they saw
- each purpose with its lawful basis, data items, retention and current choice
- timestamps
integrity: the record's latest event and its hash in the organisation's hash chain
Every event's hash covers the previous event's hash, so editing or deleting any past event breaks the chain from that point on. The console's "Verify integrity" button, and the database function verify_consent_chain(org), recompute the chain and report the first event that no longer matches.
The hash input for an event is:
sha256( prev_hash | org_id | seq | record_id | type | occurred_at_epoch_ms | payload_json )The values are joined with |; payload_json is the event payload exactly as exported.
Webhooks
Add an HTTPS endpoint in the console under Webhooks; the signing secret is shown once. Each delivery carries a Jurisphere-Signature header. Verify it against the raw request body before you parse it, reject anything older than five minutes, and deduplicate on the event id: deliveries are at least once.
import crypto from "node:crypto";
export function verifyJurisphere(secret, rawBody, header, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const t = parts.t ?? "";
const v1 = parts.v1 ?? "";
if (!/^\d+$/.test(t) || !v1) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(v1, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Express: verify against the raw body, before any JSON parsing.
app.post("/hooks/jurisphere", express.raw({ type: "application/json" }), (req, res) => {
const raw = req.body.toString("utf8");
if (!verifyJurisphere(process.env.JURISPHERE_WEBHOOK_SECRET, raw, req.get("Jurisphere-Signature") ?? "")) {
return res.sendStatus(401);
}
const event = JSON.parse(raw);
// Deliveries are at least once: skip event.id if you have already handled it.
res.sendStatus(204);
});Preference links
Send customers a signed link to their preference centre, in emails, statements or your app. Links last up to seven days. Ask us for one with your secret key:
curl -X POST https://jurisphereai.com/api/consent/v1/preference-links \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"principal_ref": "CUST-1001", "ttl_sec": 86400}'
# {"url": "https://jurisphereai.com/p/acme-finance?t=eyJvcmci…", "expires_at": "2026-11-12T15:04:05.000+05:30"}Or sign links yourself on your servers, without a network call:
import crypto from "node:crypto";
// Sign a preference-centre link yourself, without calling the API.
export function preferenceLink({ site, propertySlug, orgId, secretKey, customerRef, ttlSec = 86400 }) {
const now = Math.floor(Date.now() / 1000);
const ttl = Math.min(ttlSec, 7 * 24 * 3600); // links last at most 7 days
const payload = Buffer.from(
JSON.stringify({ org: orgId, ref: customerRef, iat: now, exp: now + ttl }),
).toString("base64url");
const secret = crypto.createHash("sha256").update(secretKey).digest("hex");
const sig = crypto.createHmac("sha256", secret).update(payload).digest("base64url");
return `${site}/p/${propertySlug}?t=${payload}.${sig}`;
}Customers without a link can always sign in with a one-time code sent to the email they gave when they consented.