DIMEAI Consent Manager Integration Guide

For free-trial and paying customers of the DIMEAI Consent Manager, the Consent Manager for Data Fiduciaries. Your trial runs for 7 days from the day we send you your trial access. Use test notices and test data only during the trial. Everything below talks to https://api.diimeai.com.

What you get

• A business API your own server calls, with an API key.
• A browser consent widget (consent-widget.js) for your website, with a web key and your registered website origin.
• Device routes behind the Android and iOS consent panels. These are part of the paid NonaShield SDK and are not in the trial.
• A tenant dashboard: notices with maker-checker approval, records and receipts, erasure and export.
• Offline verification of the exported ledger with consent_verify.py.

Every consent and every withdrawal is an append-only, hash-chained record, signed with ECDSA P-256 and ML-DSA-65. Consent is asked purpose by purpose and nothing is pre-ticked. A withdrawal is its own record. SMS and OTP are never treated as consent.

What you need from us

Your trial kit email carries these, with the tenant name to sign in with. Either admin password works with it. Keep the API key on your server only. Never put it in a web page or an app.

The flow in five steps

1. In the dashboard, create your notice and its purposes. A second person approves it (maker-checker) before it goes live. Each change is a new version.
2. Your server creates a consent session with POST /api/v1/consent/sessions, using your API key.
3. Your page or app shows the notice for that session. The person chooses purpose by purpose.
4. The choice is stored as a signed record in the chain, and the person gets a receipt.
5. Your server can check a record at any time with POST /api/v1/consent/verify, and the person can withdraw later.

Business API (your server)

All calls use your API key and the base URL https://api.diimeai.com/api/v1.

Request and response bodies are in the OpenAPI reference, which your NonaShield contact sends you. The public signing keys are at GET https://api.diimeai.com/.well-known/consent-ledger-keys.json?tenant=<slug>.

Browser widget

Load consent-widget.js from your trial kit on your own page, then mount the widget with the session your server created. The browser never holds a long-lived credential: your server creates the session, and the page receives only the session id and its short-lived token.

NonaShieldConsent.mount({
  baseUrl: 'https://api.diimeai.com',
  sessionId,                 // from your server's session call
  token,                     // from your server's session call
  publishableKey: WEB_KEY,   // the web key from your kit
  mode: 'inline',
  container: el,
  onDone: (r) => r.artefactIds
});

The widget works only from the website origin you registered. If you add a site later, ask us to register its origin. A live example is at the consent demo.

Options for the widget:

• passkey: true runs a passkey ceremony bound to the session. passkey: "required" stops if the browser has no WebAuthn.
• If you give the widget a fingerprint source, it sends a browser-fingerprint reference with the decision.
• If both are sent, both are checked and both are kept: the proof is the passkey, and the fingerprint check is stored beside it. A reference that is sent but fails is refused, never downgraded.

Android and iOS consent panel

The consent panels are part of the paid NonaShield SDK (Android: com.payshield.sdk.consent, inside the SDK you already add; there is no second SDK and no second initialize). The trial does not include the SDK or the panels: during the trial use the business API, the browser widget and the tenant dashboard.

Your server creates the session first (POST /api/v1/consent/sessions, with your API key) and hands the session id to the app (type CONSENT for present, type DASHBOARD for withdraw and list). The panel shows the notice text exactly as published, in one language, with accept and decline of equal size and nothing pre-selected, and asks for the biometric on submit. A cancelled prompt records nothing.

The Android calls are:

Set the SDK up as in the SDK Integration Guide (initialize, enroll, onUserLogin), then:

val result = PayShieldConsent.present(activity, sessionId, language = null)   // shows the panel; returns ConsentResult
PayShieldConsent.withdraw(dashboardSessionId, purposeCode)                   // one signed call; returns ConsentResult
PayShieldConsent.list(dashboardSessionId)                                    // the person's consents: List<ConsentItem>

present, withdraw and list are suspend functions and throw ConsentException(code); CANCELLED means the person closed the panel or the biometric prompt and nothing was recorded.

The device routes are signed with the standard X-PayShield-* headers. list is a POST (POST /api/v1/consent/device/list) because device routes accept only signed JSON bodies. Ask your NonaShield contact about the SDK and the iOS equivalent for your paid plan.

Assisted counter and call-centre sessions

For a person who is not at their own device, an operator records the person's choice from an attested operator device, and the operator reference is stored with the record. These records carry the ASSISTED label below.

What each proof label proves

The server sets the label from what it verified. Nothing in a request can choose or raise it.

User presence in the app is asserted by the device, not proven by the server.

Tenant dashboard

Sign in with the tenant name and either admin password from your kit. The two admins are equal: either one can write and publish a notice, and either can approve a notice the other submitted. Only you and your own admins use this dashboard. The dashboard has:

• Overview. Active and withdrawn consents, the share of events that are signed, the ledger check, and the latest events.
• Person view. Find one person by their reference (turned into a pseudonym on the server; never shown) and see their records.
• Notices. Draft, version and publish notices. Maker-checker is off by default. Turn it on for an application with the checkbox on the Notices screen: then the admin who submits a notice cannot approve it, and the other admin does.
• Records and receipts. Look up consent and withdrawal records and the receipts issued.
• Erasure and export. Erase sealed proofs, and export records for verification.

The overview, person view and records list share the same columns:

Verify offline

You do not need to trust our server to check the ledger. Export it from the dashboard or the business API, then run the verifier on your own machine:

python consent_verify.py EXPORT.json --keys KEYS.json

Get the tenant's public keys from https://api.diimeai.com/.well-known/consent-ledger-keys.json?tenant=<slug>, where <slug> is your tenant name. Fetch them over a channel you trust and keep your own copy, so that the check proves the chain was signed by keys you hold. The verifier needs no database or server and exits with 0 for a valid ledger, 1 for an invalid one and 2 if the file cannot be read. It also takes optional --anchors (receipt anchors, to detect a truncated tail), --device-keys and --sealed arguments.

Limits to know

• The notice hash in a signed record proves what the app claimed to display, not what the screen showed.
• A web fingerprint verdict is tied to the origin, the time window and the client address, not to a stored browser id.
• Device-signed consent may be switched off for your tenant until your contact enables it.
• None of this is legal advice. Have your own counsel review your notice text.

Rules

• During the trial, use test notices and test data only. Do not collect real consent from your users.
• Keep the API key on your server.
• Never use an SMS or OTP as consent.
• Our privacy notice and trial terms apply.

When the trial ends

We email you before it ends. To go on, write to contactus@diimeai.com.