Data Principals
A data principal is the technical term (from DPDPA/GDPR-style regulation) for the person whose data you're
collecting — your end user. In the API, this is the principal resource returned by /principals/register and
referenced everywhere else via your X-Principal-Token.
Identity: externalId
Every principal has an externalId, and registration is an upsert keyed on (orgId, externalId). But you are
not required to supply one when calling register.
Treat externalId as a correlation key only, not a credential — it's fine for it to be predictable (your own
user ID, an email address, whatever you already use). It's used to look up a principal, not to prove you're allowed
to act as one; that's what principal secrets and session tokens are for.
If you send an externalId
We use it as-is, and it becomes the key you upsert against:
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", "isMinor": false }'
Calling this again with the same externalId returns the existing principal rather than erroring or creating a
duplicate — so it's safe (and expected) to call it on every page load before you know whether this visitor has
been seen before. This is the recommended path whenever you already have your own stable user/account/session ID —
reusing it means you never have to store a second, CMP-specific ID just to talk to us.
If you don't send one
Some integrations genuinely can't or won't share a client-side identifier at registration time (a fully anonymous
visitor before any signup/session exists, a client that doesn't want to forward its internal user IDs, etc). In
that case, omit externalId entirely:
curl -X POST "$CMP_BASE/principals/register" \
-H "X-Org-Api-Key: $CMP_KEY" -H "Content-Type: application/json" \
-d '{ "email": "jane@example.com", "isMinor": false }'
We generate one for you (an opaque, prefixed value like dp_5e8caa5b1f1e4c2eae... — not a raw sequential number,
so it can't be enumerated) and return it in the response:
{
"entity": {
"principal": {
"id": 4821,
"externalId": "dp_5e8caa5b1f1e4c2eae9d3a2b6f7c1d90",
"email": "jane@example.com",
"...": "..."
},
"principalSecret": "dps_..."
},
"warnings": [], "errors": [], "success": true
}
What to keep: persist principalSecret (see Principal secrets below) client-side —
that's the value that mints session tokens for this principal going forward. Persisting externalId too is still
useful (for DSR/grievance submission, and if you ever integrate a server-side flow
for this same person later), but it is not what unlocks a session token from the browser anymore.
What happens if you never send any identifying data at all (no externalId, and also no email/mobile):
registration still succeeds. As long as you hold onto the principalSecret from that one response, you can still
mint session tokens and act as this principal indefinitely. Lose that, though, and — unlike losing just an
externalId — there is no recovery path; you'd register again as a new principal. See
Principal secrets for why this trade-off exists.
Fields
| Field | Type | Notes |
|---|---|---|
id | number | The principal's ID. You never pass this directly in principal-scoped calls — it's derived from your X-Principal-Token |
externalId | string | Your identifier for this person, or one we generated for you if you didn't supply one — see above |
email / mobile | string | As provided at registration |
name | string | Optional display name |
minor | boolean | See Handling Minors — changes the consent flow |
dateOfBirth | date | Optional |
preferredLanguage | string | Used to pick which notice language to show by default |
registeredAt | datetime | Set once, on first registration |
status | enum | ACTIVE, ANONYMIZED, ERASED, or MERGED — see below |
erasedAt | datetime | Set when an erasure DSR is fulfilled |
status values
ACTIVE— the normal state for a principal you can register/withdraw/grant consent for, submit DSRs and grievances on behalf of, etc.ANONYMIZED/ERASED— set when anERASUREDSR is fulfilled for this principal; identifying fields are cleared server-side. Calls against a principal in this state will generally fail, since there's no longer meaningful identity to act on.MERGED— set when an org's admin identifies this principal as a duplicate of another (the same real person registered more than once under differentexternalIds) and merges the two. This is an admin-only action your integration can't trigger via the public API; you may still encounter a principal in this state if you kept an oldexternalId/token around from before the merge — treat it the same as a stale/dead identity and have the person re-register if they return.
Principal secrets
principalSecret is a high-entropy value (e.g. dps_a1b2c3d4e5f6...), returned exactly once — in the
response to Register, and only on the call that actually creates a new
principal. It's what the browser exchanges for a session token via
Issue Token.
Why this exists, instead of just using externalId
The org API key your widget uses is, by design, visible to anyone viewing your site's network traffic — that's
what makes it safe to embed in a browser at all (see Authentication → Publishable vs. Secret keys).
If minting a session token only required that key plus a principal's externalId, then anyone who knows (or
guesses) another visitor's externalId — which might just be their email address — could mint a session token for
them and act on their behalf: read their consent status, withdraw their consent, file a DSR as them, and so on.
principalSecret closes that gap. It's disclosed exactly once, to the one browser that performed the actual
registration, and never again — not even to that same browser on a later call. Knowing an externalId is no
longer sufficient to obtain a session token for someone else.
The trade-off: no recovery if it's lost
Because principalSecret is never re-issued, a visitor who clears their browser storage (or switches devices)
loses the ability to mint new session tokens for their old principal — from your side, they look like a brand new
visitor, and register again as one. Their consent/DSR/grievance history under the old principal isn't lost on
Bytemonk's side, but you have no way to reach it without the original principalSecret.
This is an accepted trade-off for the anonymous browser-widget flow specifically, since there's no email/SMS verification step to recover through. If your integration has its own login system, prefer Server-Side Integration instead — a logged-in user never depends on browser storage surviving, since your own backend re-establishes their session token on demand using your own authentication.
Self-service session tokens
Every principal-scoped endpoint (consent/grant, consent/withdraw, consent/status, dsr, grievances,
guardian/register) requires a session token, sent as X-Principal-Token. There are two ways to mint one,
matching the two integration modes:
# Browser widget — exchange the principalSecret from registration
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 }
The raw token is only ever returned in this response — the server stores just its hash. It's valid for 15 minutes and reusable across calls during that window (mint it once per session, not before every request), and can be explicitly invalidated early by your own "log out" action if you build one.
What you can't do with the public API
The public API is deliberately narrow — it has no endpoint to list all principals, search principals, or fetch one principal's full profile by ID. Those are admin-facing operations (the Bytemonk dashboard's Data Principals page). If your integration needs to show a user their own data, use the DSR Access request flow rather than trying to read it directly.