Skip to main content

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.

When to use this instead of the browser widget

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​

  1. 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.
  2. 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" }'
Response
{
"entity": { "token": "8a1d2f6c-....-....-....-............" },
"warnings": [],
"errors": [],
"success": true
}
Attribute consent to your site with sourceDomain

Add 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).

Note the different base path

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.

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

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-....-....-....-............"
Mixing key types on purpose

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.

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:

reasonMeaning
GRANTEDThe latest decision covering this purpose is a yes, and it has not expired.
DENIEDThe person said no to this purpose.
WITHDRAWNThey gave consent and later withdrew it.
EXPIREDThe consent is older than the banner's expiry setting; ask again.
REQUIRES_RECONSENTYour privacy policy version changed since they consented; ask again.
SNOOZE_ENDEDThe person withdrew this purpose "for now" and the date has passed; treat it as undecided and ask again.
NO_RECORDNothing has been recorded for this person and purpose yet.
UNKNOWN_PRINCIPALNo 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.
  • GET and PUT /api/v1/server/cmp/principals/profile?externalId=... read and write the person's profile answers.
  • GET /api/v1/server/cmp/codes lists 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.