Skip to main content

Verifiable Parental Consent (VPC)

This guide walks you through implementing the VPC widget in just a few steps, allowing you to quickly meet regulatory requirements while providing a smooth user experience for both children and their parents.

Try the k-ID Dev Explorer

Use the k-ID Dev Explorer, an open source developer sandbox, to test VPC flows and view all traffic in an event log. You can also use it as a starting point for your own VPC implementation.

The End-to-end Widget is a comprehensive solution that handles the complete compliance flow in a single interface, covering age gate, VPC, data notices, permissions, and preferences all in one seamless experience. This widget can be used by parents either on the child's device or on their own device, providing maximum flexibility for the consent process.

What's an age gate?​

An Age Gate is a mechanism used to collect and verify a user's age before allowing access to age-restricted content, features, or services. Age gates are required by regulations in many jurisdictions to ensure compliance with laws governing digital content access for minors.

Age gates serve several important purposes:

  • Regulatory Compliance: Meet legal requirements for verification in different jurisdictions
  • Content Protection: Prevent minors from accessing inappropriate content
  • Data Privacy: Ensure proper handling of children's data according to regulations such as COPPA, GDPR-K, and others
  • Parental Control: Enable parents to make informed decisions about their children's digital access
Jurisdiction-Aware Intelligence

By providing the user's jurisdiction, the End-to-end Widget automatically determines the best methods for collecting their age (if not already provided) and intelligently determines whether VPC is necessary based on that jurisdiction's specific regulations. This ensures compliance without requiring you to implement complex jurisdictional logic.

Verifiable Parental Consent (VPC) is a regulatory requirement that ensures parents or trusted adults can provide informed consent for children to access digital content, services, or features. When a child attempts to access age-restricted content, the system creates a Challenge that requires parental approval before access can be granted.

The VPC flow typically involves:

  1. Age Collection: Determining the child's age through appropriate methods
  2. Challenge Creation: Creating a consent challenge when parental approval is required
  3. Parental Notification: Notifying parents through various channels (email, QR code)
  4. Consent Processing: Parents review and approve/deny the request
  5. Session Management: Creating or updating the child's permissions based on consent results

Prerequisites​

Before you begin, you'll need:

  1. A k-ID Product: Create and configure your product in the k-ID Compliance Studio
  2. API Key: Generate your API key from the Developer Settings page of your product in the Compliance Studio
  3. Webhook Endpoint (optional but recommended): Set up a secure HTTPS endpoint to receive challenge and session events. For more detail, see Webhooks.

Step 1: Initiate the VPC flow​

Call the /widget/generate-e2e-url API to create an end-to-end widget URL that handles the complete VPC flow. This returns a unique URL for users to complete the age collection and parental consent process.

tip

Use the API reference with your API key to quickly generate your VPC widget URL.

Important

For your implementation, this should be a server-to-server call to protect your API key from being exposed in client-side code.

Example request​

POST /api/v1/widget/generate-e2e-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA"
}

Configuration flags​

The optional flags parameter allows you to customize which parts of the flow to skip:

  • skipDataNotices: Skip data notices and consent collection
  • skipVerification: Skip verification step
  • skipPermissions: Skip permission management
  • skipPreferences: Skip preference settings

Example response​

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/widget?token=eyJhbGciOiJFUzM4NCIs..."
}

Step 2: Display the VPC widget​

Use the returned URL to create an iframe in your website or app. Users complete the age collection and trusted adult consent process through this interface, with available methods automatically adapting to jurisdictional requirements.

HTML Implementation​

<div id="vpc-container">
  <iframe 
    id="vpc-widget"
    src="WIDGET_URL" 
    width="100%" 
    height="600"
    frameborder="0"
    allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
  </iframe>
</div>

The iframe presents users with multiple verification methods such as:

  • AgeKey: A reusable and anonymous age-proof generated after an initial verification process.
  • Facial Age Estimation: Privacy-preserving age estimation using a device's camera
  • ID Document Verification: Government-issued ID verification

The specific methods available depend on the jurisdiction and your product configuration in the Compliance Studio. For more detail, see Verification Methods

The widget presents users with:

  • Age Collection: Jurisdiction-appropriate age collection methods
  • Data Notices: Data notices to accept, depending on the product's configuration in the Compliance Studio
  • Permissions: Permissions to manage, depending on the product's configuration in the Compliance Studio
  • Parental Consent Challenge: If the user is determined to be a minor, a challenge is created for trusted adult approval

The specific flow depends on the jurisdiction and your product's configuration in the Compliance Studio.

Step 3: Handle challenge and session events​

When a Challenge is created for parental consent, you'll need to handle the results. Implementations should use a combination of client-side and server-side methods: client-side events are best for controlling UI elements, while for data integrity, the actual results should come from either a webhook or a call to /challenge/get-status.

Client-side (DOM events)​

Use DOM Events for responsive UI updates when challenges are created or resolved. For detailed information about the event structure, see Widget.AgeGate.Challenge.

const handleMessage = (event) => {
  const message = event.data;
  
  if (message.eventType === "Widget.AgeGate.Challenge") {
    if (message.data.status === "PASS") {
      // Parent approved consent - update UI immediately
      console.log("Consent approved:", message.data.sessionId);
      updateUI(message.data.sessionId);
    } else if (message.data.status === "FAIL") {
      // Parent denied consent - update UI immediately
      console.log("Consent denied");
      updateUI();
    }
  }
};

window.addEventListener("message", handleMessage);

Server-side (webhooks, API calls)​

Use webhooks or API calls for data integrity and reliable state management. For data integrity, always verify results with events from webhooks or by calling /challenge/get-status rather than relying solely on DOM Events.

Webhooks​

For detailed information about webhook event structures, see Challenge.StateChange and Session.ChangePermissions.

Configure your webhook endpoint to receive Challenge.StateChange and Session.ChangePermissions events:

Challenge.StateChange event:

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "683409f1-2930-4132-89ad-827462eed9af",
    "productId": 42,
    "status": "PASS",
    "sessionId": "0ad1641f-c154-4c2-8bb2-74dbd0de7723",
    "approverEmail": "parent@example.com",
    "kuid": "123456"
  }
}

Session.ChangePermissions event:

{
  "eventType": "Session.ChangePermissions",
  "data": {
    "id": "78c299b2-5c33-4bde-84fe-8fc950fc7a96",
    "productId": 42
  }
}

API calls​

Query the challenge status with the challenge ID with /challenge/get-status:

GET /api/v1/challenge/get-status?id=683409f1-2930-4132-89ad-827462eed9af

Response:
{
  "id": "683409f1-2930-4132-89ad-827462eed9af",
  "status": "PASS",
  "sessionId": "0ad1641f-c154-4c2-8bb2-74dbd0de7723"
}

Webhook configuration​

For the VPC widget, ensure your webhook endpoint is configured to receive:

These events are essential for maintaining proper access control and ensuring compliance with parental consent requirements.

What's next?​

Now that you've implemented the VPC widget, explore these resources to enhance your integration:

With k-ID's VPC widget, you can quickly achieve compliance with parental consent regulations while providing families with a smooth, privacy-focused experience.