Skip to main content

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​

FieldTypeRequiredNotes
externalIdstringYour own identifier for this person. Omit it and we generate one for you — see below
emailstring
mobilestring
namestring
isMinorbooleanDefaults to false if omitted. See Handling Minors
dateOfBirthstring (date)ISO-8601 date, e.g. "2014-03-01"
preferredLanguagestringe.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, not entity directly.
  • principalSecret is present only in the first-registration response — it's never sent again, on any later call, for this externalId. 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​

FieldTypeRequired
principalSecretstring✅
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​

FieldTypeRequired
externalIdstring✅
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​

FieldTypeRequired
externalIdstring✅
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​

FieldTypeRequiredNotes
namestring✅Guardian's name
relationstring✅e.g. "Mother", "Father", "Legal Guardian"
contactstringPhone or email
proofTypeenumOne of AADHAAR, PAN, PASSPORT, BIRTH_CERTIFICATE, SCHOOL_ID, OTHER
proofRefstringA 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.

Registering a guardian is not enough on its own

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.