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 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
- A Publishable API key — see Authentication.
- 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 withnoticeGroupKey="privacy-policy"andlanguage="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"
}'
{
"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 onceprincipalSecret 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..." }'
{
"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"
{
"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.
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.
{
"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
- Handling Minors & Guardians — if your product serves users under 18.
- Embedding a Widget — a single hosted script that handles the banner and actually blocks gated third-party scripts/cookies until consent is granted.
- Server-Side Integration — the alternative flow for an authenticated, logged-in-user settings page instead of an anonymous browser widget.
- Data Principal Requests — letting principals request access/correction/erasure.