Principals API
Background reading: Data Principals.
Register
POST /principals/register
Auth: Org key only (Publishable or Secret).
Upsert on (orgId, externalId) — if a principal with this externalId already exists, this call updates any
field you send that differs from what's on file (email, mobile, name, isMinor, dateOfBirth,
preferredLanguage) and returns the updated principal, rather than erroring or creating a duplicate. Omit a field
(or send the same value already on file) to leave it untouched. This is also how you keep a principal's contact
details current after first registration — there's no separate "update profile" endpoint; call register again
with the changed field(s).
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
externalId | string | Your own identifier for this person. Omit it and we generate one for you — see below | |
email | string | ||
mobile | string | ||
name | string | ||
isMinor | boolean | Defaults to false if omitted. See Handling Minors | |
dateOfBirth | string (date) | ISO-8601 date, e.g. "2014-03-01" | |
preferredLanguage | string | e.g. "en", "hi" |
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",
"mobile": "9876543210",
"name": "Jane Doe",
"isMinor": false,
"preferredLanguage": "en"
}'
Response — 200 OK, first time this externalId is registered
{
"entity": {
"principal": {
"id": 42,
"orgId": 1,
"externalId": "user-8231",
"email": "jane@example.com",
"mobile": "9876543210",
"emailHash": "0da36ae9...",
"mobileHash": "34b7c55e...",
"name": "Jane Doe",
"minor": false,
"dateOfBirth": null,
"preferredLanguage": "en",
"registeredAt": "2026-07-04T04:47:50.649+00:00",
"status": "ACTIVE",
"erasedAt": null
},
"principalSecret": "dps_a1b2c3d4e5f6..."
},
"warnings": [],
"errors": [],
"success": true
}
Response — 200 OK, externalId already existed (repeat call)
{
"entity": {
"principal": { "id": 42, "orgId": 1, "externalId": "user-8231", "...": "..." }
},
"warnings": [],
"errors": [],
"success": true
}
The returned principal reflects any field updates this call just applied (see above) — it's not necessarily
identical to what a previous call returned for the same externalId.
Note two things that differ from a plain principal response elsewhere in this API:
- The principal is nested under
entity.principal, notentitydirectly. principalSecretis present only in the first-registration response — it's never sent again, on any later call, for thisexternalId. See Principal secrets below for why.
externalId is optional — what happens if you omit it
externalId is internally a required, unique-per-org field on every principal — but you don't have to be the one
who supplies it. If your request omits externalId (or sends it blank), the server generates an opaque one (e.g.
dp_5e8caa5b1f1e4c2eae9d3a2b6f7c1d90) and returns it in entity.principal.externalId.
Keep whatever comes back, but note externalId itself is no longer the credential you use to mint a session
token from the browser (that's principalSecret now — see below). externalId still matters for
DSR and Grievances submission today, and for
server-to-server token issuance.
principalSecret is not just an identifier
Unlike externalId (which is just a correlation key — fine to be predictable, like an email address),
principalSecret is a high-entropy bearer credential. It exists specifically so that knowing/guessing a
principal's externalId, combined with your (necessarily public, for a browser widget) org key, is not enough
to mint a session token for them — see Data Principals → Principal secrets
for the full rationale. Store it client-side the moment you see it; there is no endpoint to retrieve it again.
Failure
400 Bad Request with CMP_PRINCIPAL_REGISTRATION_FAILED (code 18005) if registration fails — see
Error Codes.
Issue Token
POST /principals/token
Auth: Org key only (Publishable or Secret) — no principal token needed, since this endpoint is how you get one.
Exchanges a principalSecret (obtained once from Register) for a short-lived (15 minute), reusable
session token. This is the browser-widget flow — see Server-Side Integration for
the equivalent server-to-server flow, which uses externalId instead.
Request body
| Field | Type | Required |
|---|---|---|
principalSecret | string | ✅ |
curl -X POST "$CMP_BASE/principals/token" \
-H "X-Org-Api-Key: $CMP_KEY" -H "Content-Type: application/json" \
-d '{ "principalSecret": "dps_a1b2c3d4e5f6..." }'
Response — 200 OK
{
"entity": { "token": "c67f282f-5029-4971-9dd5-099b22fc73c7" },
"warnings": [],
"errors": [],
"success": true
}
The raw token is only ever returned here — the server only stores its hash. Send it as an X-Principal-Token
header on every subsequent principal-scoped call (see Authentication).
It's valid for 15 minutes and reusable across calls within that window — you don't need to re-mint between, say, a
grant and a status check.
Failure
400 Bad Request with CMP_PRINCIPAL_TOKEN_FAILED (code 18006) — most commonly, principalSecret doesn't match
any registered principal for this org (wrong value, or the principal was registered under a different org key).
Revoke token
POST /principals/token/revoke
Auth: 🔒 principal token. Invalidates the exact token presented in X-Principal-Token immediately, ahead of
its natural 15-minute expiry — e.g. for a "log out" action. No request body; there's no separate field to say
which token to revoke, it's always the one authenticating this request.
curl -X POST "$CMP_BASE/principals/token/revoke" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: c67f282f-5029-4971-9dd5-099b22fc73c7"
Response — 200 OK
{ "entity": true, "warnings": [], "errors": [], "success": true }
Any later call using this same token now gets 401 Unauthorized, the same as an expired one — mint a fresh token
to continue.
Server-to-server token issuance
POST /api/v1/server/cmp/principals/token
Note the different base path — this is not under /api/v1/public/cmp. Full details, including when to use this
instead of the browser flow above: Server-Side Integration.
Auth: Secret key only — a Publishable key gets 403 Forbidden here.
Request body
| Field | Type | Required |
|---|---|---|
externalId | string | ✅ |
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": "user-8231" }'
Response — 200 OK
Same shape as Issue Token above — { "entity": { "token": "..." }, ... }. The token itself is
longer-lived than the browser-widget flow's — 60 minutes, not 15 — since a logged-in settings/preference-center
session commonly runs longer than a single banner interaction.
Rotate principalSecret
POST /api/v1/server/cmp/principals/rotate-secret
Server-to-server only, same base path as token issuance above. Mints a fresh principalSecret for an
already-registered externalId, replacing the stored one so it stops working immediately. For the case where the
original one-time principalSecret from Register was lost client-side (cleared localStorage, a new
device, etc.) but your own backend still knows the externalId and holds a Secret key — previously the only
options were "the original secret, if you still have it" or "register again and treat them as a new principal,"
with no way to reconnect the two.
Auth: Secret key only — a Publishable key gets 403 Forbidden here.
Request body
| Field | Type | Required |
|---|---|---|
externalId | string | ✅ |
curl -X POST "https://api.bytemonk.co/api/v1/server/cmp/principals/rotate-secret" \
-H "X-Org-Api-Key: sec_..." -H "Content-Type: application/json" \
-d '{ "externalId": "user-8231" }'
Response — 200 OK
{ "entity": { "principalSecret": "dps_f7e6d5c4b3a2..." }, "warnings": [], "errors": [], "success": true }
Hand this back to whatever client-side flow needs it (localStorage, same as the original). Every session token
already minted for this principal keeps working until its own natural expiry — rotation only affects future
principalSecret → token exchanges via Issue Token.
Failure
400 Bad Request with CMP_GENERAL_ERROR (code 18000) if externalId doesn't match any registered principal
for this org.
Register guardian
POST /guardian/register
Auth: 🔒 principal token — required, and it must be the minor's own token (obtained the same way any
principal token is: register the minor, then mint a token for them). Registers guardian info against whichever
principal that token identifies; there is no minorId field in the body.
Required before that principal can have consent granted on their behalf — see Handling Minors & Guardians.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | ✅ | Guardian's name |
relation | string | ✅ | e.g. "Mother", "Father", "Legal Guardian" |
contact | string | Phone or email | |
proofType | enum | One of AADHAAR, PAN, PASSPORT, BIRTH_CERTIFICATE, SCHOOL_ID, OTHER | |
proofRef | string | A reference to wherever you store the actual proof document |
curl -X POST "$CMP_BASE/guardian/register" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: <the minor's own session token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Priya Sharma",
"relation": "Mother",
"contact": "priya@example.com",
"proofType": "AADHAAR",
"proofRef": "verification-doc-ref-123"
}'
Response — 201 Created
{
"entity": {
"id": 3,
"orgId": 1,
"guardianName": "Priya Sharma",
"guardianRelation": "Mother",
"guardianContact": "priya@example.com",
"proofOfRelationType": "AADHAAR",
"proofOfRelationRef": "verification-doc-ref-123",
"timestamp": "2026-07-04T10:00:00.000+00:00",
"verificationStatus": "UNVERIFIED"
},
"warnings": [],
"errors": [],
"success": true
}
verificationStatus is one of UNVERIFIED (always the starting value from this call), MANUALLY_VERIFIED, or
REJECTED — the latter two are only ever set by an org admin reviewing the record, never by this endpoint.
verificationStatus starts at UNVERIFIED — DPDPA Sec 9(2) requires guardian consent to be verifiable, not
just recorded. An admin on the org's side must review and manually verify this record (setting it to
MANUALLY_VERIFIED) before POST /consent/grant will succeed for this minor; until then, grant fails with
CMP_GUARDIAN_NOT_VERIFIED (code 18010) even though a guardian record now exists. If the admin instead rejects
it (REJECTED), grant continues to fail the same way. The verification action itself has no public endpoint — it
happens on the org's own admin side — but you can poll the current status yourself, see
Check guardian status below.
Failure
500 Internal Server Error with a CMP_GENERAL_ERROR (code 18000) if the token's principal somehow doesn't
belong to this org (shouldn't happen in normal use — the token was minted for this org already), or if name or
relation is missing ("Please provide the guardian's name." / "Please specify the guardian's relationship to you." respectively — both safe to show the data principal directly).
Check guardian status
GET /guardian/status
Auth: 🔒 principal token — the minor's own token, same as Register guardian. Lets a
minor's own session check their guardian record's current verificationStatus directly, instead of the only
option previously available: attempt Grant Consent and infer the state
from the failure. Useful for showing "your guardian's consent is pending review" rather than a blind retry.
curl "$CMP_BASE/guardian/status" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: <the minor's own session token>"
Response — 200 OK
Same shape as Register guardian's response — the current guardian record for this
principal, reflecting whatever an admin has done with it since (verificationStatus may now be
MANUALLY_VERIFIED or REJECTED, with verifiedBy/verifiedAt populated).
Failure — 404 Not Found
Returned if no guardian record has been registered yet for this principal — treat this the same as "guardian details not collected yet," and show the guardian-details form.