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, don't 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

Server-only API calls

Important

All widget URL generation endpoints should only be called from your 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 front end 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 (for example, https://yourgame.com)
• Wildcard subdomains: Use wildcard patterns for subdomains (for example, 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.

Important

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

info

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;payment;publickey-credentials-get;publickey-credentials-create"
  width="100%"
  height="600"
></iframe>

Permission Breakdown:

• camera - Required for facial age estimation
• payment - Required for credit card verification
• publickey-credentials-create - Required for Age Key creation
• publickey-credentials-get - 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);
});