Best Practices

Age Verification Best Practices

Handling Verification Failures

When implementing access age verification, developers should check the failureReason field in verification results to properly handle failures:

• Fraudulent Activity Detection: If a verification fails and the failureReason is fraudulent-activity-detected, do not allow additional verification attempts for that user.
• Other Failure Reasons: For all other failure reasons (such as age-criteria-not-met or max-attempts-exceeded), implement rate limiting to prevent abuse while allowing legitimate retry attempts. Allow a maximum of 3 verification attempts per 24-hour period. This prevents users from repeatedly attempting to bypass the verification system while providing reasonable retry opportunities for legitimate users

Security Recommendations

Backend-Only API Calls

Important: All widget URL generation endpoints should only be called from your backend server, never directly from client-side code. Your k-ID API key is a secret credential that must be protected:

• Store API keys securely using a secrets manager
• Never expose API keys in frontend JavaScript, mobile app code, or any client-facing code
• Never store API keys on client devices or in client-side storage

Target Origins Configuration

CDK offers the ability to configure target origins in the Compliance Studio to control which domains can embed your widgets. This setting controls the frame-ancestors directive of the Content Security Policy. As an optional security measure, it's recommended to evaluate your risk tolerance and decide whether to implement target origin restrictions based on your security requirements.

Configuration Options:

• Specific domains: Set exact domains for production use (e.g., https://yourgame.com)
• Wildcard subdomains: Use wildcard patterns for subdomains (e.g., https://*.yourgame.com)
• Unrestricted: Leave empty or set to * for unrestricted embedding (not recommended for production)

Security Benefits: Target origins prevent attackers from embedding your verification flows in transparent iframes on malicious sites, where they could overlay other content and trick users into inadvertently clicking on verification elements.

Implementation Notes:

• Configure separate target origins for each environment (test/live)
• Ensure target origins are properly configured for all production endpoints before going live.
• Each subdomain requires its own entry unless using wildcards
• Only certain k-ID pages can be embedded in iframes regardless of target origin settings (verification pages, widgets, and VPC flows)
• All other k-ID pages (family management, account settings) are always blocked from iframe embedding

iframe Permissions

Always include the necessary permissions in your iframe allow attribute:

<iframe 
  src="WIDGET_URL"
  allow="camera;autoplay;payment;publickey-credentials-get;publickey-credentials-create"
  width="100%"
  height="600"
></iframe>

Permission Breakdown:

• camera - Required for facial age estimation
• autoplay - Used by facial age estimation (optional, prevents console warnings)
• payment - Optional for credit card verification (enables browser payment API)
• publickey-credentials-get/create - Required for Age Key verification

Origin Validation

Always validate the origin of incoming messages:

window.addEventListener('message', (event) => {
  // Validate origin based on environment
  const validOrigins = [
    'https://family.k-id.com',        // Live environment
    'https://family.test.k-id.com'    // Test environment
  ];
  
  if (!validOrigins.includes(event.origin)) {
    return; // Ignore messages from unauthorized origins
  }
  
  // Process the event
  handleWidgetEvent(event.data);
});