k-ID Dev Explorer

日本語版はこちら | 한국어 버전 | 中文版

An interactive developer tool for exploring and testing k-ID's Compliance Developer Kit (CDK) and AgeKit+ flows. Built with Next.js, this tool provides a visual interface to test all CDK flow types, observe API traffic in real-time, and understand how to integrate k-ID's age verification and compliance flows into your application.

The k-ID Compliance Developer Kit (CDK) and AgeKit+ provide a set of pre-built flows for age verification, parental consent, and compliance management. This tool helps developers understand how to integrate these flows by providing:

• Visual Flow Testing: Test all CDK flow types with real API calls
• Real-time API Traffic: Observe requests and responses as flows execute
• Traffic Logging: Download API traffic logs for debugging and analysis
• Webhook Receiver: Test webhook integrations with ngrok support

For complete documentation, visit the k-ID Developer Hub.

Make sure you have ngrok installed on your system:

• macOS: brew install ngrok
• Windows: Download from ngrok.com
• Linux: Download from ngrok.com

First, install the dependencies:

npm install

1. Copy the example environment file:

   cp .env.example .env.local

2. Get your API key from the k-ID Compliance Studio

3. Edit .env.local and add your API key:

   K_ID_API_KEY=your_actual_api_key_here
   K_ID_API_URL=https://game-api.test.k-id.com
   NEXT_PUBLIC_LOCALE=en

   Replace your_actual_api_key_here with your actual API key from the Compliance Studio. The K_ID_API_URL defaults to the test environment. Change this to the live mode URL when ready.

   Setting the UI Language: The NEXT_PUBLIC_LOCALE variable controls the language of the user interface. Set it to:

   • en for English (default)
   • ja for Japanese
   • ko for Korean
   • zh for Chinese

   After changing the locale, restart the development server for the changes to take effect.

   Webhook Signature Validation (optional): The WEBHOOK_SECRET variable enables webhook signature validation using HMAC-SHA256. If provided, all incoming webhook requests will be validated against this secret. Get your webhook secret from the k-ID Compliance Studio product settings. If not provided, webhook signature validation will be skipped (useful for testing without signature validation).

For more information on getting started with k-ID, see the k-ID Developer Hub.

npm run dev

This command starts both the Next.js development server and an ngrok tunnel:

• Server runs on http://localhost:3100
• Ngrok tunnel creates external HTTPS URL
• Webhook URL: https://[random].ngrok-free.app/api/webhook

Note: The ngrok URL will change each time you restart the development server unless you have an ngrok account and auth token.

📱 QR Code for Mobile Access: A QR code is automatically generated and displayed in the "Public Tunnel Access" section. Scanning this QR code with your phone allows you to access the k-ID Dev Explorer on your mobile device, enabling you to test CDK flows on mobile devices directly.

When developing locally, age key creation and validation will not work unless running over HTTPS, as this is a requirement of WebAuthn. The ngrok tunnel provides HTTPS access, which is required for testing flows that involve age key creation or validation.

The k-ID Dev Explorer provides an interactive way to test k-ID CDK flows:

1. Select a Flow: Choose a CDK flow type from the dropdown menu (e.g., Age Gate Widget, Access Age Verification, Age Appeal, etc.)

2. Enter Required Fields: Fill in the necessary fields for the selected flow:

   • Jurisdiction: Required for most flows (e.g., "US-CA", "GB")
   • Age Criteria: Age number or age category (required for some flows)
   • Subject Information: Email, ID, date of birth, or claimed age (optional for some flows)
   • Locale: Language/locale code (e.g., "en-GB") - optional for some flows

3. Click "Embed CDK Flow": This initiates the API call to k-ID and embeds the returned URL in the iframe on the right side of the screen.

4. Observe the Traffic: Watch the Events & API Traffic window to see:

   • API requests being made to k-ID
   • API responses with URLs and IDs
   • PostMessage events from the iframe
   • Webhook events (if configured)
   • Any errors or warnings

5. Step Through the Flow: Interact with the embedded CDK flow in the iframe. As you progress through the verification steps, observe the events appearing in the event window.

6. Preview on Different Devices: Use the Device (Mobile / Tablet) and Orientation (Portrait / Landscape) toggle above the iframe to see how the widget's own responsive layout adapts. The iframe is scaled to fit the column while its internal viewport reports the target device size.

7. Hand Off to a Real Phone via the Console: Below the iframe, the Console panel shows the widget's short URL as a QR code, plus Copy URL and Open in new tab buttons. Scan the QR from your phone to continue the flow on a real device. If Compliance Studio is configured to send webhooks to your ngrok URL, the QR flips to a PASS ✓ / FAIL ✗ overlay when the Verification.Result / Challenge.StateChange webhook arrives.

8. Download Traffic Logs: Click the Download button in the Events & API Traffic section to save a copy of all API traffic as a text file for analysis or debugging.

The selector groups flows into AgeKit+ API (age assurance methods), CDK API (server-side CDK endpoints), and CDK Widgets (hosted widget URLs embedded in the iframe):

AgeKit+ API

• Access Age Verification: Verify a user's age before granting access
• Facial Age Estimation: Estimate age using facial recognition
• ID Verification: Verify identity using government-issued ID
• AgeKey Verification: Passkey-based age verification
• ConnectID Verification: Verify age using ConnectID
• Email Age Estimation: Estimate age from an email address
• Trusted Adult Verification: Verify through trusted adult confirmation
• Age Appeal: Allow users to appeal an age verification decision

CDK API

• Age Gate Check: Server-side CDK Custom flow that checks age gate requirements and returns a challenge when age assurance is needed
• Session Upgrade Age Assurance: Upgrade an existing session with permissions that require age assurance

CDK Widgets

• Age Gate Widget: Present age verification options to users
• End-to-End Widget: Complete verification, consent, and permission flow (VPC)
• Direct Notices Widget: Display compliance notices directly
• Manage Session Permissions Widget: Manage permissions for an existing session

For detailed documentation on each flow, visit the k-ID Developer Hub.

The application includes a webhook receiver that can be accessed both locally and externally via ngrok tunnels.

The application automatically detects and displays the external URL when ngrok is running:

• 🌐 External URL: https://[random].ngrok-free.app/api/webhook (when ngrok is active)
• 🏠 Local URL: http://localhost:3100/api/webhook (fallback when ngrok is not running)

Configuring Your Webhook URL: To receive webhook events from k-ID, you need to configure the webhook URL in the k-ID Compliance Studio. Navigate to your product settings and set the webhook receiver URL to the external URL displayed above (when using ngrok) or your deployed application URL. The webhook URL must be publicly accessible for k-ID to send events to your application.

• Event Window: All webhook events appear in real-time in the main interface
• Server-Sent Events: Automatic updates when webhooks are received
• Event Details: Full request information including headers, body, method, and timestamp
• Signature Validation: Webhook signature validation status is displayed for each webhook event:
  • ✓ Signed: Webhook signature is valid (green badge)
  • ✗ Invalid signature: Webhook signature does not match (red badge)
  • ⚠ No signature: Webhook request has no signature header (yellow badge)
  • ○ Signature validation not configured: WEBHOOK_SECRET is not set (gray badge)
• Copy Functionality: Click the copy button to copy webhook data to clipboard

The application supports webhook signature validation using HMAC-SHA256. To enable signature validation:

1. Get your webhook secret from the k-ID Compliance Studio product settings
2. Add WEBHOOK_SECRET to your .env.local file:

   WEBHOOK_SECRET=your_webhook_secret_here

3. Restart the development server

When WEBHOOK_SECRET is configured, the application will:

• Validate webhook signatures using HMAC-SHA256
• Check for signature headers: x-k-id-signature, x-signature, or k-id-signature
• Display signature validation status in the event log for each webhook event

If WEBHOOK_SECRET is not provided, webhook signature validation will be skipped (useful for testing without signature validation).

Copy .env.example to .env.local and configure:

• K_ID_API_KEY - Your k-ID API key (required for CDK flows)
  • Get your API key from the k-ID Compliance Studio
• K_ID_API_URL - k-ID API base URL (defaults to https://game-api.test.k-id.com)
  • Test environment: https://game-api.test.k-id.com
  • Production environment: https://game-api.k-id.com
• NEXT_PUBLIC_LOCALE - Language code for the UI (optional, defaults to 'en')
  • Supported values: en (English), ja (Japanese), ko (Korean), zh (Chinese)
• PORT - Server port (defaults to 3100, optional)
• NEXT_PUBLIC_APP_URL - Override local URL (optional)
• WEBHOOK_SECRET - Webhook secret for signature validation (optional)
  • If provided, webhook requests will be validated using HMAC-SHA256 signature verification
  • Get your webhook secret from the k-ID Compliance Studio product settings
  • If not provided, signature validation will be skipped (useful for testing)

• npm run dev - Start development server with ngrok tunnel
• npm run dev:ngrok - Start ngrok tunnel only
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint

• Ngrok creates HTTPS tunnels by default for security
• The application automatically detects both HTTP and HTTPS tunnels
• Webhook events are stored in memory (last 100 events)
• SSE connections include heartbeat to keep connections alive
• Ngrok tunnel information refreshes every 10 seconds
• The event window only shows meaningful events (API traffic, webhook payloads, JS events)

• k-ID Developer Hub - Complete k-ID documentation and integration guides
• k-ID Compliance Studio - Get your API keys and manage your k-ID integration
• k-ID CDK Documentation - CDK overview and getting started
• Next.js Documentation - Next.js framework documentation
• Ngrok Documentation - Ngrok tunneling documentation