Skip to main content

Quickstart

This walks through the complete, minimal browser-widget flow: register a principal, mint a session token, fetch a notice, and record their consent choice. By the end you'll have made every call needed for a basic consent banner.

This is the browser-widget flow (Mode A)

This page covers integrating from an anonymous, client-side context — a website consent banner with no login. If you're integrating from your own backend on behalf of users already logged into your own product, see Server-Side Integration instead — it's a shorter flow with different credentials.

Prerequisites​

  1. A Publishable API key — see Authentication.
  2. At least one published (ACTIVE) consent notice — created and published from the Bytemonk dashboard under CMP → Notices & Purposes. If you haven't published one yet, do that first; every call below assumes a notice already exists with noticeGroupKey="privacy-policy" and language="en".

Set these as shell variables so the examples below are copy-pasteable:

export CMP_BASE="https://api.bytemonk.co/api/v1/public/cmp"
export CMP_KEY="pub_9f8a1c2e..."

1. Register the visitor as a data principal​

Call this the first time you see a visitor (e.g. on page load, or right before you need to show the consent banner). externalId is your own identifier for this person — a user ID, session ID, or anything stable you already use. If a principal with that externalId already exists for your org, this call just returns the existing one — it's safe to call on every page load.

externalId is optional — if you don't have a stable identifier yet, omit it and the server generates one, returned in entity.principal.externalId. See Data Principals for what to do with it.

curl -X POST "$CMP_BASE/principals/register" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "user-8231",
"email": "jane@example.com",
"mobile": "9876543210",
"name": "Jane Doe",
"isMinor": false,
"preferredLanguage": "en"
}'
Response — first time this externalId is registered
{
"entity": {
"principal": {
"id": 42,
"orgId": 1,
"externalId": "user-8231",
"email": "jane@example.com",
"mobile": "9876543210",
"name": "Jane Doe",
"minor": false,
"preferredLanguage": "en",
"registeredAt": "2026-07-04T04:47:50.649+00:00",
"status": "ACTIVE"
},
"principalSecret": "dps_a1b2c3d4e5f6..."
},
"warnings": [],
"errors": [],
"success": true
}
principalSecret is shown exactly once

principalSecret is only present in the response the first time a given externalId is registered — calling register again later for the same visitor (which is expected, safe, and idempotent) returns the principal without it. This is deliberate: it's a high-entropy credential, not just an identifier, and it's what mints session tokens for this visitor from here on — see Data Principals → Principal secrets for why it exists and why it isn't just externalId.

Store principalSecret immediately, client-side (localStorage/cookie), the moment you see it. If you lose it, there is no recovery path other than treating this visitor as new — they'll register again and get a fresh one.

2. Exchange principalSecret for a session token​

curl -X POST "$CMP_BASE/principals/token" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "Content-Type: application/json" \
-d '{ "principalSecret": "dps_a1b2c3d4e5f6..." }'
Response
{
"entity": { "token": "c67f282f-5029-4971-9dd5-099b22fc73c7" },
"warnings": [],
"errors": [],
"success": true
}

Keep this token in memory (or short-lived storage) for the rest of the session — it's valid for 15 minutes and reusable across every call below, so mint it once, not before every request. Full field reference: Principals API.

3. Fetch the active notice to render your banner​

GET /notice doesn't need a principal token — it's not principal-specific data, just the org key:

curl "$CMP_BASE/notice?groupKey=privacy-policy&lang=en" \
-H "X-Org-Api-Key: $CMP_KEY"
Response
{
"entity": {
"id": 12,
"noticeGroupKey": "privacy-policy",
"language": "en",
"version": 2,
"title": "Our Privacy Notice",
"content": "We collect your email and mobile number to...",
"status": "ACTIVE",
"purposes": [
{
"id": 8,
"purposeCode": "marketing",
"name": "Marketing Communications",
"description": "Send promotional emails and SMS",
"dataCategories": [
{ "code": "email", "name": "Email" },
{ "code": "mobile", "name": "Mobile" }
],
"legalBasis": "CONSENT",
"retentionPeriodDays": 365,
"mandatory": false
},
{
"id": 9,
"purposeCode": "analytics",
"name": "Product Analytics",
"description": "Understand how you use our product",
"dataCategories": [
{ "code": "email", "name": "Email" }
],
"legalBasis": "VOLUNTARILY_PROVIDED_DATA",
"retentionPeriodDays": 730,
"mandatory": true
}
]
},
"warnings": [],
"errors": [],
"success": true
}

Render title/content, and one toggle per entry in purposes — using name/description as the label, listing dataCategories[].name so the visitor sees exactly what data that purpose covers (per DPDPA Sec 5 — see Consent Notices → Purposes), and disabling the toggle (forced on) when mandatory is true. Keep entity.id — this is the noticeId you'll pass to the grant call. Full field reference: Notices API.

Always re-fetch, never hardcode a notice ID

Your integration should always call /notice?groupKey=...&lang=... rather than hardcoding a specific notice id. When the org publishes a new version, this call transparently starts returning the new one — your code doesn't change. See Versioning Notices for why this matters.

4. Record the visitor's choice​

When the visitor clicks "Accept selected" (or "Accept all"), send their per-purpose choices — the org key and the session token from step 2 are both required here:

curl -X POST "$CMP_BASE/consent/grant" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: c67f282f-5029-4971-9dd5-099b22fc73c7" \
-H "Content-Type: application/json" \
-d '{
"noticeId": 12,
"purposeSelections": { "marketing": false, "analytics": true },
"method": "WIDGET"
}'

Note there's no principalId in the body — the token from step 2 is what identifies which principal this consent belongs to.

Response (201 Created)
{
"entity": {
"id": 77,
"status": "ACTIVE",
"consentMethod": "WIDGET",
"timestamp": "2026-07-04T10:15:00.000+00:00",
"sha256Checksum": "a1b2c3...",
"purposeRecords": [
{ "id": 1, "status": "DENIED" },
{ "id": 2, "status": "GRANTED" }
]
},
"warnings": [],
"errors": [],
"success": true
}

That's it — you've registered a principal, minted a session token, shown them a notice, and recorded their consent. Full field reference: Consent API.

Next steps​