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>" }'
{ "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.
4. Guardian consent still needs to be verified before granting
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
minoron the registered principal (you already have this from the registration response — no extra call needed). - If
minor === trueand you haven't yet collected guardian details, show a guardian-details form instead of (or before) the consent banner, and callPOST /guardian/registerwith 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
| Situation | What happens |
|---|---|
POST /consent/grant called for a minor with no guardian registered | Grant 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 org | Fails with a general error |
POST /guardian/register called with a missing/invalid/expired X-Principal-Token | 401 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.