K id consent and challenges
Implements the parental-consent flow for k-ID minors — the GUARDIAN-managed path where a trusted adult grants permissions for a child (COPPA parental consent, EU GDPR-Kids verifiable parental consent, UK AADC equivalent). Supports both approaches: Pattern A (default) builds a fully custom consent screen (QR + OTP + email + direct link) and calls /challenge/send-email and /challenge/generate-otp directly with top-level polling — a brand-fit, inline experience; Pattern B is a fast-path fallback using the end-to-end widget (/widget/generate-e2e-url — iframe handles age gate, consent, data notices, permissions) or the manage-permissions widget (/widget/generate-manage-session-permissions-url — post-gate consent only). Use when building the consent screen, wiring challenge send / status endpoints, handling `challengeId` without a session, or diagnosing why approvals don't reach the app. Not for age assurance or threshold verification (k-id-age-verification), not for the age gate itself (k-id-age-gate).From its SKILL.md
npx -y skills add kidentify/skills --skill k-id-consent-and-challengesAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
15.2 KB, as published. Nobody here has run it
k-ID Parental Consent and Challenges
When the age gate concludes the user is a minor in a jurisdiction that
requires verifiable parental consent (VPC) — COPPA in the US, GDPR-Kids
in the EU, UK AADC, and similar regimes — k-ID returns a challenge.
A guardian approves it out-of-band, and your app must detect the
approval and continue. This skill covers the canonical consent screen,
the challenge endpoints, and the polling lifecycle that keeps it
reliable.
This skill is the GUARDIAN-managed path only — a trusted adult is
approving permissions on behalf of a child. It is not the path for
age assurance, threshold verification, or any scenario where the user
themselves must prove their age (UK Online Safety Act 18+ features,
Brazil ECA Digital loot-boxes, Australia social media minimum age).
Those flows live in k-id-age-verification.
When to use
Use this skill when the user is:
- Building the consent screen shown to a minor waiting on a parent.
- Embedding the k-ID end-to-end or manage-permissions widget to cover consent inside an iframe.
- Calling
/challenge/send-email,/challenge/generate-otp,/challenge/get, or/challenge/get-status. - Polling for challenge state changes and materializing the session when consent is granted.
- Handling a
challengeIdthat arrives without asessionId. - Debugging "the parent approved but the child's app never unlocks".
Two approaches — custom UX or widget
There are two ways to run the consent flow. Pick one per product.
Pattern A — custom consent screen + polling (the default)
Build the QR + OTP + email + direct link screen by hand, call the underlying challenge endpoints, and run polling at the top level of the app (outside the consent modal). The result is a parental-consent flow that matches the product's visual identity exactly, renders inline (no iframe), and stays consistent with the age gate and permission UI built the same way.
Pattern A wins when: the product wants a polished, brand-fit consent experience that feels native to the rest of the app; has already built a custom age gate; or targets platforms where iframes aren't practical (Unity WebGL, consoles, native desktop). This is the default path for production integrations.
Pattern B — end-to-end or manage-permissions widget (fast-path fallback)
If the integration must be small, simple, and as fast as possible to
ship, use the end-to-end widget: one iframe covers age gate +
parental consent + data notices + permissions + parental preferences.
Parental consent is initiated automatically when the age entered
triggers it, and the widget handles QR, OTP, email, and direct link
natively. Call
POST /widget/generate-e2e-url.
If the product already has a session and only needs consent for a
specific permission upgrade, use the manage-permissions widget:
POST /widget/generate-manage-session-permissions-url.
In both cases the product listens for DOM events
(Widget.AgeGate.Result, Widget.DataNotices.ConsentApproved,
Widget.ExitReview) or handles the redirect callback. No polling is
required. The widget surfaces the final state; the product just needs
to call /session/get after the event to materialize the session
client-side.
Pattern B wins when: the integration must be small, simple, and fast — proofs of concept, internal tools, early-stage games — or the product can accept the iframe look in exchange for minimum code and minimum compliance surface area.
The rest of this skill covers Pattern A step by step. Pattern B users can stop here and jump to the relevant widget event documentation.
Core steps (Pattern A — custom consent)
1. Show QR + OTP + email + direct link together
Parents approve in whichever lane is easiest for them — present all four in parallel. Offering only one lane (typically email) measurably lowers approval rates.
- QR code — parent scans with their phone camera. Encodes the
challenge.url. - OTP code — human-entered at
asktoplay.com. Pull the code fromchallenge.oneTimePassword(returned by/challenge/getand/challenge/generate-otp). - Email — "Send a link to my parent's email" with an input field.
Calls
/challenge/send-email. - Direct link — "This device belongs to a parent" button that
navigates the current device to
challenge.urlin the SAME window (or iframe — neverwindow.open).
OTP copy must say "Enter at asktoplay.com" — not family.k-id.com.
asktoplay.com is the memorable, kid-friendly domain that redirects
to Family Connect and is much easier to read aloud.
2. Call the right endpoint for each lane
| Lane | Endpoint | Reads |
|---|---|---|
| QR / Direct link | Already in challenge.url from the age-gate response | challenge.url |
| OTP | POST /challenge/generate-otp (or GET /challenge/get) | challenge.oneTimePassword |
POST /challenge/send-email | body: { challengeId, email } |
The endpoint is /challenge/send-email, NOT /challenge/send-consent-email.
send-consent-email returns 404. For full shapes see
docs.k-id.com/api/endpoints/send-email
and sibling endpoints under "Challenges".
3. Poll at the top level of the app, not inside the modal
Mount the polling loop at the top level of the signed-in app — above any modal, gated control, or route component. The modal can close for many reasons (user dismissal, re-render on approval, navigation) and polling that is bound to the modal's lifecycle stops with it, leaving the approval undetected.
The top-level loop:
- Runs every 10 seconds as long as there is any active
challengeId(including a minor in limited-access mode, i.e. a pending challenge withchallenge.childLiteAccessEnabled: true). - Wakes up on
visibilitychangeandfocusevents. - Does not depend on the modal being open.
useEffect(() => {
if (!pendingChallengeId) return;
let cancelled = false;
const tick = async () => {
if (cancelled) return;
const status = await getChallengeStatus(pendingChallengeId);
if (status.state === 'PASS' && !cancelled) {
await handleChallengePass(status);
}
};
const id = setInterval(tick, 10_000);
const wake = () => tick();
document.addEventListener('visibilitychange', wake);
window.addEventListener('focus', wake);
void tick();
return () => {
cancelled = true;
clearInterval(id);
document.removeEventListener('visibilitychange', wake);
window.removeEventListener('focus', wake);
};
}, [pendingChallengeId]);
4. Handle BOTH variants of PASS
PASS does not always include a sessionId. Code must handle
both cases:
if (status.sessionId) {
// Swap whatever placeholder sessionId the app was holding
// (for the pending-challenge / limited-access state) for the
// real one returned by /challenge/get-status, then hydrate.
setSessionId(status.sessionId);
await fetchSession();
} else {
// Re-run /age-gate/check with the age the user originally entered;
// the minor now has an approved challenge, so a session will mint.
await checkAge(enteredAge, jurisdiction);
}
This is why k-id-age-gate insists on
persisting enteredAge — without it this recovery path is impossible.
5. Retry session fetch after adopting the real sessionId
After swapping in the sessionId from /challenge/get-status,
GET /session/get may return 404 for 1–2 seconds while the session
propagates. Retry up to 3 times with 1-second delays. A single 404
is not a failure.
6. While waiting for consent, render the app in limited-access mode
When the product has opted into limited-access mode in Compliance
Studio AND the challenge response has
challenge.childLiteAccessEnabled: true, the minor can continue
into the app with a reduced permission set before the parent has
approved. This is a valid end state, not an error. Render the main
app UI with the reduced permissions (or with pendingChallenge
lock labels on gated controls) and keep polling. See
k-id-sessions-and-permissions for the lock labels this state
uses ("Waiting for parent", "Get parent permission"). If the
product has NOT opted into limited-access mode, or the challenge
response has childLiteAccessEnabled: false, the minor must wait
on the consent screen until consent completes.
Gotchas
Both patterns
- Consent is GUARDIAN-managed, always. This flow only applies when
a trusted adult is granting permissions on behalf of a minor. It
does not apply to adult age assurance or to
verifiedAgeThresholdpermissions — those are user-self-verified and live ink-id-age-verification. - Default to a custom consent screen. Custom gives the cleanest brand fit and the smoothest minor-waiting experience, and keeps the consent flow consistent with a custom age gate built the same way. Drop to the end-to-end widget only when the integration must be small, simple, and fast to ship — the widget handles jurisdiction-appropriate consent copy and data notices out of the box, which custom screens have to keep in sync manually.
Pattern A — custom
- Endpoint is
/challenge/send-email, not/challenge/send-consent-email. The second form looks more descriptive but does not exist. 404. - Parallel consent lanes, not sequential. Showing email-only (or QR-then-email-fallback) measurably reduces approval rate.
- Polling MUST live at the top level of the app, not in the consent modal. If the modal owns the interval, approvals that arrive right after a dismissal (or a fast-dismiss + reopen) are missed.
PASSdoes not always includesessionId. When it does, swap it in and call/session/get. When it doesn't, re-call/age-gate/checkwith the storedenteredAgeso a session is minted against the now-approved challenge.- Retry
/session/getafter swapping in the real sessionId. 1–2s propagation delay is normal. A single 404 is not an error. - OTP copy is
asktoplay.com, notfamily.k-id.com. Parents and kids read the OTP aloud —asktoplay.comis shorter and easier. - Direct link must NEVER be
window.openortarget="_blank". Use an in-page iframe or a same-window navigation. New-tab flows lose the referrer and break approval attribution on some browsers. - Limited-access mode (
childLiteAccessEnabled: true) is a valid end state, not an error. Do not block the app with a "waiting for parent" spinner — render it with a reduced permission set. - Background session refresh is separate from challenge polling. A 30-second session refresh loop also runs at the top level of the app. Challenge polling is 10s. Don't merge them.
- Don't synthesize a sessionId for a limited-access minor. There
is no session yet. Downstream APIs will reject a fake ID. Track
the
challengeIdexplicitly in app state until/challenge/get-statusreturns a realsessionId.
Defaults
- Poll interval: 10s for challenges, 30s for session refresh.
- Wake triggers:
visibilitychange,focus. - Post-PASS session fetch: 3 retries, 1s apart.
- Consent screen layout: 2×2 grid on desktop (QR, OTP, email, direct); stacked vertically on mobile.
- Email input: plain
<input type="email">, no strict regex —/challenge/send-emailvalidates.
Validation step
Run the checklist for the pattern you built.
Pattern A — custom
Confirm all of the following end-to-end with a test parent account:
- Approve via QR on parent's phone — child's app unlocks within 15s without any user action.
- Approve via OTP on a parent laptop — same.
- Approve via emailed link — same.
- Approve via direct link on the child's device — child's app unlocks after the Family Connect flow returns.
- Close the consent modal before approving — then approve on any lane. Child's app still unlocks (proves top-level polling).
- Reload the child's app mid-wait — the pending challenge rehydrates from state and polling resumes.
Pattern B — widget
- Server generates an end-to-end (or manage-permissions) widget URL and it loads in an iframe without CSP errors.
- A minor age entered in the widget triggers the parental-consent flow inside the same iframe without additional API calls from the product.
- After a test parent approves, the widget fires
Widget.AgeGate.Result(orWidget.ExitReview) with the finalsessionId; a follow-up/session/getreturns full permissions. - No client-side polling loop was required.
Next steps
- Gate returned a
challenge→ you arrived here correctly. - Gate returned a
session→ go tok-id-sessions-and-permissions. - Unverified adult verification →
k-id-age-verification. - Webhooks for parental-consent events →
k-id-webhooks. - Server wiring for challenge endpoints →
k-id-server-trust-boundary.
Canonical references:
- VPC concept
- Challenges concept
POST /widget/generate-e2e-urlPOST /widget/generate-manage-session-permissions-urlPOST /challenge/send-emailPOST /challenge/generate-otpGET /challenge/getGET /challenge/get-statusparentalconsent.grantedwebhookchallenge.statechangewebhook- Choose integration: CDK widgets vs custom UX