Authentication
The public CMP API uses two layers of credentials, not one:
- An organization API key (
X-Org-Api-Keyheader) — identifies which organization a request belongs to. - A principal token (
X-Principal-Tokenheader) — identifies which specific data principal (end user) a request is acting on behalf of. Required on every endpoint that reads or writes a specific principal's data (granting/withdrawing consent, filing a DSR or grievance, registering a guardian, etc).
An org API key on its own can only ever prove which org a request belongs to — it's a value that, for the browser-widget integration pattern, is necessarily visible to anyone viewing your site's network traffic (see Publishable vs. Secret keys below). If that key alone were enough to act on any principal, anyone holding it could read or modify any of your end users' consent/DSR/grievance records just by guessing their principal ID. The principal token closes that gap — see How principal tokens work.
Getting an API key
API keys are generated from the Bytemonk dashboard: CMP → API Keys → Generate API Key. Give it a descriptive
label (e.g. "Production Website Widget", "Mobile App Backend") so you can tell keys apart later, and choose a
key type — see below.
When you generate a key, the raw value is displayed once, immediately after creation. Bytemonk never stores the raw key — only a salted hash of it — so if you lose it, you cannot recover it. You'll need to revoke it and generate a new one.
Publishable vs. Secret keys
Publishable (pub_...) | Secret (sec_...) | |
|---|---|---|
| Safe to embed in browser JS / a mobile app | Yes — this is its entire purpose | Never |
Works against /api/v1/public/cmp/* (the browser-facing surface) | Yes | Yes |
Works against /api/v1/server/cmp/* (server-to-server surface) | No — rejected with 403 | Yes, and only this type may |
| Where you'd use it | A website consent banner, mobile app — anywhere the key has to reach an untrusted client | Your own backend, calling on behalf of an already-authenticated user of your app — see Server-Side Integration |
Pick the key type when you generate it. If you're building the standard embeddable consent banner described in Quickstart, you want Publishable. If you're integrating from your own backend on behalf of users who are already logged into your own product, you want Secret — see Server-Side Integration for that flow specifically.
A Secret key is exactly as sensitive as a database password. Treat it the same way: environment variable / secrets
manager on your server, never in a <script> tag, never in a mobile app binary, never committed to a public repo.
There is no undo once one leaks other than revoking it.
Sending the org key
Every request to /api/v1/public/cmp/* (or /api/v1/server/cmp/*) must include the key in an X-Org-Api-Key header:
curl https://api.bytemonk.co/api/v1/public/cmp/notice?groupKey=privacy-policy&lang=en \
-H "X-Org-Api-Key: pub_9f8a1c2e..."
There is no separate "org ID" parameter anywhere in the public API — the key itself resolves to your organization server-side, so a request can never accidentally read or write another organization's data.
How principal tokens work
A principal token is a short-lived (15 minute), reusable session credential scoped to one specific data principal.
It's what every principal-scoped endpoint (consent/grant, consent/withdraw, consent/status, dsr,
grievances, guardian/register, ...) uses to determine who the request is acting on behalf of — you never pass
a principalId in the request body for these calls, it's derived entirely from the token.
There are two ways to obtain one, matching the two key types above:
- From the browser (Publishable key): register the principal, store the
principalSecretreturned exactly once at that moment, then exchange it for a token viaPOST /principals/token. See Quickstart for the full walkthrough. - From your backend (Secret key): mint a token directly for a known
externalIdviaPOST /api/v1/server/cmp/principals/token— noprincipalSecretneeded, because holding a Secret key already proves you're a trusted backend that authenticated this user yourself. See Server-Side Integration.
Send the token on every subsequent call as its own header, alongside the org key:
curl -X POST "$CMP_BASE/consent/grant" \
-H "X-Org-Api-Key: pub_9f8a1c2e..." \
-H "X-Principal-Token: c67f282f-5029-4971-9dd5-099b22fc73c7" \
-H "Content-Type: application/json" \
-d '{ "noticeId": 12, "purposeSelections": { "marketing": true }, "method": "WIDGET" }'
It's reusable for the full 15 minutes — mint it once per session and reuse it across grant/withdraw/status/DSR calls, rather than re-minting before every single request.
What happens if a credential is missing, invalid, or wrong type
| Situation | Response |
|---|---|
No X-Org-Api-Key header sent | 401 Unauthorized |
| Org key doesn't match any known key, or has been revoked | 401 Unauthorized |
Publishable key used against /api/v1/server/cmp/* | 403 Forbidden |
No X-Principal-Token sent to an endpoint that requires one | 401 Unauthorized |
X-Principal-Token doesn't match, has expired, or was revoked | 401 Unauthorized |
None of these return the normal error body shape (see Error Codes) — authentication failures are rejected before your request ever reaches application logic.
Key hygiene
- One key per integration surface, not one key shared across every property you own. A leaked key for your marketing site's cookie banner shouldn't also expose your mobile app's consent flow — generate separate keys and revoke independently if one is compromised.
- Match the key type to where it's actually used. Publishable keys are designed to tolerate being public;
Secret keys are not — see Publishable vs. Secret keys above. Using a Publishable
key where you meant to use Secret just gets you a
403; using a Secret key where a Publishable one belongs is the actual risk to avoid. - Rotate on suspicion. Revoking a key is immediate and irreversible from the dashboard's API Keys page — a
revoked key simply starts returning
401on every subsequent call.