Skip to main content

Authentication

The public CMP API uses two layers of credentials, not one:

  1. An organization API key (X-Org-Api-Key header) — identifies which organization a request belongs to.
  2. A principal token (X-Principal-Token header) — 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).
Why two layers

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.

The raw key is shown exactly once

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 appYes — this is its entire purposeNever
Works against /api/v1/public/cmp/* (the browser-facing surface)YesYes
Works against /api/v1/server/cmp/* (server-to-server surface)No — rejected with 403Yes, and only this type may
Where you'd use itA website consent banner, mobile app — anywhere the key has to reach an untrusted clientYour 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.

Never send a Secret key to a browser

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 principalSecret returned exactly once at that moment, then exchange it for a token via POST /principals/token. See Quickstart for the full walkthrough.
  • From your backend (Secret key): mint a token directly for a known externalId via POST /api/v1/server/cmp/principals/token — no principalSecret needed, 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​

SituationResponse
No X-Org-Api-Key header sent401 Unauthorized
Org key doesn't match any known key, or has been revoked401 Unauthorized
Publishable key used against /api/v1/server/cmp/*403 Forbidden
No X-Principal-Token sent to an endpoint that requires one401 Unauthorized
X-Principal-Token doesn't match, has expired, or was revoked401 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 401 on every subsequent call.