Skip to content
Full DPDP obligations apply from 13 May 2027. Check your readiness →

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. 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. 2. Add the widget to your pages

    HTML
    <script src="https://jurisphereai.com/consent/v1/widget.js"
            data-key="pk_live_…" async></script>
  3. 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. 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.

    Shell
    curl -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

ModeUse it forHow
Form modeWeb formsAdd data-jurisphere-consent to the form
Direct modeSingle-page apps, custom flowsJurisphere.consent.request()
Cookie modeAnalytics and marketing cookiesdata-cookie-mode on the script tag

Attributes

AttributeOnWhat it does
data-keyscriptYour publishable key. Required.
data-apiscriptAPI origin, if not the script's own origin.
data-langscript or formPreferred notice language, e.g. hi. Defaults to the page's lang.
data-cookie-modescriptShow the cookie banner.
data-jurisphere-consentformThe collection point slug.
data-principal-fieldformName of the field holding your customer reference.
data-principal-refformThe customer reference itself, if it isn't in a field.
data-contact-fieldformOptional 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

JavaScript
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.

JavaScript
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)
});
statusMeaning
grantedThe person chose and the record was saved.
cancelledThe person closed the notice without choosing.
unavailableOur API couldn't be reached. The choice is queued and retried.
errorMisconfigured: 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.

HTML
<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.

KeyLooks likeWhere it's usedCan do
Publishablepk_live_… / pk_test_…The browser (widget), mobile appsRead published notices; record consent; create rights requests. Only from the property's allowed origins.
Secretsk_live_… / sk_test_…The client's servers onlyEverything: 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.example are allowed). App and offline properties may omit Origin.
  • Secret keys never belong in a browser. A secret key sent with an Origin header 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> (or idempotency_key in 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

json
{ "error": { "code": "personal_identifier_not_allowed", "message": "principal_ref looks like an email or phone number. Send your own customer reference instead." } }
CodeHTTPWhen
bad_request400Body fails validation (details lists the fields)
personal_identifier_not_allowed400principal_ref looks like an email, phone, PAN or Aadhaar
notice_version_mismatch409The notice the person saw is no longer the published one; reload it
unauthorized401Missing, malformed, unknown or revoked key
forbidden403Publishable key used for a secret-only call, or the origin isn't allowed
not_found404Unknown collection point, record or request
conflict409Same idempotency_key with a different body
rate_limited429Over the per-key limit; retry after Retry-After seconds
internal500Our 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).

json
{
  "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: true to create an active record. 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_url keeps only the address of the page. Query strings and #fragments are 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 updated event.

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.

json
{ "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.granted
  • consent.updated
  • consent.withdrawn
  • request.created
  • request.updated
  • request.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:

text
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.

js
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.

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:

text
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.

Node.js
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);
});

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:

Shell
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:

Node.js
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.