Skip to main content

Handling Minors & Guardians

DPDPA-style regulation requires verifiable parental/guardian consent before processing a minor's personal data. The CMP enforces this: a minor cannot grant their own consent until a guardian has been registered for them.

1. Register the principal with isMinor: true​

curl -X POST "$CMP_BASE/principals/register" \
-H "X-Org-Api-Key: $CMP_KEY" -H "Content-Type: application/json" \
-d '{
"externalId": "user-9001",
"name": "Minor User",
"dateOfBirth": "2014-03-01",
"isMinor": true
}'

This is the minor's own principal record. As with any first registration, the response includes a principalSecret — keep it, since you need it in step 2.

2. Mint a session token for the minor​

Guardian registration is a 🔒 principal-token-gated endpoint, and specifically requires the minor's own token — not the guardian's, and not just a minorId field. Whoever is registering guardian info must already be able to prove control of the minor's principal, the same way any principal-scoped action requires:

curl -X POST "$CMP_BASE/principals/token" \
-H "X-Org-Api-Key: $CMP_KEY" -H "Content-Type: application/json" \
-d '{ "principalSecret": "<the minor'\''s principalSecret from step 1>" }'
Response
{ "entity": { "token": "c67f282f-5029-4971-9dd5-099b22fc73c7" }, "warnings": [], "errors": [], "success": true }

In practice, this means whoever is running through this flow on the minor's behalf (typically a parent, in your own UI) needs to be the same session that just registered the minor — e.g. a parent filling out a signup form for their child, where your app holds onto the minor's principalSecret for the duration of that flow.

3. Register a guardian for that principal​

curl -X POST "$CMP_BASE/guardian/register" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: c67f282f-5029-4971-9dd5-099b22fc73c7" \
-H "Content-Type: application/json" \
-d '{
"name": "Priya Sharma",
"relation": "Mother",
"contact": "priya@example.com",
"proofType": "AADHAAR",
"proofRef": "verification-doc-ref-123"
}'

There's no minorId field — the token from step 2 is what identifies which principal this guardian info attaches to. proofType is one of a fixed set (AADHAAR, PAN, PASSPORT, BIRTH_CERTIFICATE, SCHOOL_ID, OTHER); proofRef is a reference to wherever you actually store the verification document, since the CMP itself doesn't handle document upload.

Registering a guardian isn't enough on its own — DPDPA Sec 9(2) requires this consent to be verifiable, not just recorded. The response's verificationStatus starts at UNVERIFIED, and POST /consent/grant will keep failing for this minor (CMP_GUARDIAN_NOT_VERIFIED, code 18010) until someone on the org's side manually reviews and verifies it. The verification action itself has no public endpoint — it's an admin-side action, so your integration can't trigger it directly — but you can poll the current status yourself via Check guardian status rather than inferring it from a grant failure; the practical implication is that consent for a newly-registered minor may not be grantable immediately, and your UI should show "pending verification" (from that status check) rather than assuming grant always succeeds right after guardian registration.

Once verified, POST /consent/grant — using that same minor's session token — succeeds normally, the same call described in the Quickstart. If you attempt to grant consent for a minor with no guardian registered at all, or with a guardian still UNVERIFIED, the call fails — see the error table below.

What your UI should do differently for minors​

  • Before showing the standard consent banner, check minor on the registered principal (you already have this from the registration response — no extra call needed).
  • If minor === true and you haven't yet collected guardian details, show a guardian-details form instead of (or before) the consent banner, and call POST /guardian/register with the minor's own token, as above.
  • Only render the normal purpose-toggle banner once a guardian is on file.

Errors specific to this flow​

SituationWhat happens
POST /consent/grant called for a minor with no guardian registeredGrant fails with CMP_GUARDIAN_MISSING (code 18009) — see Error Codes
POST /consent/grant called for a minor whose guardian record is still UNVERIFIED (or was REJECTED)Grant fails with CMP_GUARDIAN_NOT_VERIFIED (code 18010)
POST /guardian/register called with a token whose principal isn't a minor, or is a minor belonging to another orgFails with a general error
POST /guardian/register called with a missing/invalid/expired X-Principal-Token401 Unauthorized, no envelope — mint a fresh token for the minor and retry

Both guardian-related grant failures have their own stable error codes (18009/18010) — branch on errors[0].code directly instead of string-matching errors[0].message, and prefer Check guardian status to proactively show "pending verification" UI rather than waiting for a grant attempt to fail.