Server-Side Integration
If your product already has its own login system, and you want to show a "Privacy Settings" or "Manage My Consent" page to a user who's already logged in, you don't need the anonymous browser-widget flow from Quickstart at all. This page covers the alternative: your own backend calls the CMP API directly, on behalf of a user it has already authenticated itself.
Use this flow when the person you're showing consent/DSR/grievance information to is already logged into your product — you have your own session/JWT/whatever proving who they are. Use the Quickstart flow instead for an anonymous, pre-login surface like a public cookie banner.
Why this is a different flow, not just a shortcut
The browser-widget flow exists to solve a problem this one doesn't have: proving "this token request really came
from the same person who registered" without any login system to lean on. That's why it needs a
principalSecret — see Data Principals → Principal secrets.
Here, your backend already solved that problem — your own login system authenticated the user before they ever
reached this page. So the CMP API lets your backend mint a session token directly from your own internal user
identifier (externalId), with no principalSecret round-trip needed. This is safe specifically because reaching
this endpoint at all requires a Secret API key — see
Authentication → Publishable vs. Secret keys — which,
by definition, never reaches a browser. Holding that key is what stands in for "I already verified this user."
The flow
- Your backend generates a Secret key from the dashboard (CMP → API Keys → Generate API Key, key type Secret) and stores it as a server-side secret — same handling as a database password, never sent to any client.
- When a logged-in user opens their privacy/consent settings page, your backend calls the server-to-server token
endpoint using that user's own internal ID as
externalId:
curl -X POST "https://api.bytemonk.co/api/v1/server/cmp/principals/token" \
-H "X-Org-Api-Key: sec_..." \
-H "Content-Type: application/json" \
-d '{ "externalId": "internal-user-48213" }'
{
"entity": { "token": "8a1d2f6c-....-....-....-............" },
"warnings": [],
"errors": [],
"success": true
}
sourceDomainAdd an optional "sourceDomain": "www.example.com" to the request body and consent given with that token is recorded
against your site. The hosted Preference Center runs in an iframe, so without this its
consent would be attributed to the Bytemonk host instead of your website. Because only the holder of your Secret key
can set it, it can't be spoofed by a web page. Omit it to keep the default (the browser's own origin).
This is /api/v1/server/cmp/..., not /api/v1/public/cmp/.... It's also not reachable with a Publishable key — you'll
get 403 Forbidden if you try.
- Your backend then uses that token exactly like the browser-widget flow does from here — either:
- hand it to the frontend for that page's session (short-lived, 60 minutes, so this is low-risk to expose
browser-side for the duration of one visit), and let the frontend call the public
/api/v1/public/cmp/*endpoints directly with it plus a Publishable key, - keep the token server-side entirely and proxy every CMP call through your own backend, never exposing it to the browser at all, or
- skip building your own UI entirely and embed Bytemonk's own hosted Preference Center — see Preference Center — which is exactly a frontend built the first way, already built for you.
- hand it to the frontend for that page's session (short-lived, 60 minutes, so this is low-risk to expose
browser-side for the duration of one visit), and let the frontend call the public
Either way, every principal-scoped endpoint documented in the API Reference — consent status/grant/withdraw, DSR, grievances — works identically from here on; they don't know or care which of the two flows minted the token.
# Example: reading this user's current consent status, using the token from step 2
curl "https://api.bytemonk.co/api/v1/public/cmp/consent/status?noticeId=12" \
-H "X-Org-Api-Key: pub_..." \
-H "X-Principal-Token: 8a1d2f6c-....-....-....-............"
Minting the token is the one step gated on the Secret key (step 2). Everything after that — actually reading/ writing consent data — uses the same Publishable-key-accepting public endpoints your browser widget would use. This is intentional: the Secret key's whole job is authenticating "this backend already vouches for this user"; once you have a token, the rest of the API doesn't need to re-litigate that.
Checking consent from your backend
Before your backend processes personal data for a purpose (sending a marketing email, loading an analytics pixel for a
logged-in user), ask whether that person currently consents. This uses your Secret key and the same externalId you
registered the person with.
curl "https://<your-bm-api-host>/api/v1/server/cmp/consent/check?externalId=user-4821&purposeCode=analytics_cookies&sourceDomain=shop.example.com" \
-H "X-Org-Api-Key: <your secret key>"
sourceDomain is optional. When given, only consent given on that website (or its consent group) counts; leave it out to
look across every website.
{
"entity": {
"allowed": false,
"reason": "EXPIRED",
"consentRecordId": 77,
"recordedAt": "2025-09-01T10:15:00.000+00:00",
"expiresAt": "2026-09-01T10:15:00.000+00:00",
"sourceDomain": "shop.example.com"
},
"errors": [],
"success": true
}
Process the data only when allowed is true. reason says why:
reason | Meaning |
|---|---|
GRANTED | The latest decision covering this purpose is a yes, and it has not expired. |
DENIED | The person said no to this purpose. |
WITHDRAWN | They gave consent and later withdrew it. |
EXPIRED | The consent is older than the banner's expiry setting; ask again. |
REQUIRES_RECONSENT | Your privacy policy version changed since they consented; ask again. |
SNOOZE_ENDED | The person withdrew this purpose "for now" and the date has passed; treat it as undecided and ask again. |
NO_RECORD | Nothing has been recorded for this person and purpose yet. |
UNKNOWN_PRINCIPAL | No person is registered with that externalId. |
To stay in step without calling this each time, subscribe to the consent.granted and consent.withdrawn
webhooks; both say which website the decision came from and the state of every purpose afterwards.
Reading preferences, profile answers and codes
Three more calls use the same Secret key and externalId:
GET /api/v1/server/cmp/consent/preferences?externalId=...&purposeCode=...returns what the person chose inside a purpose (topics, channel, frequency), only while the purpose is granted. Use it to decide how to contact someone.GETandPUT /api/v1/server/cmp/principals/profile?externalId=...read and write the person's profile answers.GET /api/v1/server/cmp/codeslists the notice, purpose and data category codes you can use.
Details and response shapes are in the Preference Center API.
What "browser storage cleared" means in this flow
Nothing — that's the point. Unlike the anonymous widget flow (where losing a principalSecret means starting over
as a new principal), a logged-in user re-authenticates through your login system every time, and your backend
re-mints a fresh token on demand. There's no principalSecret for this flow at all, and nothing durable that needs
to survive on the client between visits.
Registering a principal for this flow
The same POST /principals/register endpoint from Quickstart
applies — call it (with a Secret or Publishable key, either works) using your own internal user ID as externalId,
the first time you need a CMP principal to exist for that user (e.g. right after they sign up in your product, or
lazily the first time they open the privacy settings page). You can safely ignore principalSecret in the
response for this flow — it's only relevant to the browser-widget path.
If this same user also later needs the anonymous browser-widget flow (e.g. they visit a separate marketing site
that isn't behind your login), and the principalSecret from that first registration was never captured or has
since been lost, your backend can mint a fresh one with Rotate principalSecret
— no need to treat them as a brand-new principal just because the original secret is gone.