Skip to main content

Widget.ExitReview Clarification and API Updates

We've clarified when to close widget UI for age verification and VPC flows, and added redirectUrl support to the MegaWidgetOptions schema.

What's New​

Widget.ExitReview Clarification​

We've updated the documentation to clarify that Widget.ExitReview is the signal that should determine when to close the UI for age verification and VPC flows.

Updated documentation:

  • Age verification guide - Added guidance on listening for Widget.ExitReview to close the verification UI
  • VPC guide - Added guidance on listening for Widget.ExitReview to close the VPC widget UI
  • CDK embedded flow - Added guidance on listening for Widget.ExitReview to close the widget UI

All language versions (English, Japanese, Simplified Chinese, and Korean) have been updated with this clarification.

API Updates​

redirectUrl in MegaWidgetOptions​

The MegaWidgetOptions schema now includes redirectUrl support, consistent with age verification request schemas. This allows you to specify a redirect URL when using the end-to-end widget.

Updated schemas:

  • MegaWidgetOptions now includes redirectUrl field with reference to #/components/schemas/RedirectUrl

This change is available in all OpenAPI specification files (English, Japanese, Simplified Chinese, and Korean).

Documentation Improvements​

Product Image Specifications​

Added recommended aspect ratios and resolutions for product images in Compliance Studio:

  • Logo: 1:1 (square), 512×512px
  • Banner: 3:1 (wide), 2430×810px

ageCategory Now Included in FAIL Status Webhook Events

We've updated the Verification.Result webhook event to include the ageCategory field in FAIL status events when age data is available.

What's New​

ageCategory in FAIL Status Events​

The ageCategory field is now included in Verification.Result webhook events for FAIL status when:

  • failureReason is age-criteria-not-met
  • Age data is available (both age.low and age.high are present)

This provides more complete information about the user's age category even when verification fails due to age criteria not being met, enabling better analytics and logging while maintaining clear access control boundaries.

Updated Documentation​

The Verification.Result documentation has been updated to reflect this change:

  • Fields table: Updated description to clarify when ageCategory is present for FAIL status
  • Key differences table: Clarified when ageCategory is present for webhook events vs API endpoint
  • FAIL status field presence rules: Updated to show ageCategory as "Sometimes included" with specific conditions
  • Complete field matrix: Updated to show ageCategory as "sometimes²" for FAIL status in webhooks
  • Example payloads: Added ageCategory to the FAIL status example to demonstrate the new behavior
  • Implementation checklist: Updated guidance for handling ageCategory in FAIL status
  • Implementation notes: Clarified the behavior of ageCategory for both PASS and FAIL statuses

Important Notes​

  • Access control: Even when ageCategory is present in FAIL status events, it should never be used for access control decisions. Always use the status field to determine access.
  • Consistency: This update applies to both webhook events and API endpoint responses
  • Language support: All language versions (English, Japanese, Simplified Chinese, and Korean) have been updated

Next Steps​

  • Review the updated Verification.Result documentation
  • Update your integration to handle ageCategory in FAIL status events if needed
  • Remember: Never use ageCategory for access control when status is FAIL, even if the field is present. Use it only for analytics, logging, or informational purposes.

New Sessions and Permissions Guide and Documentation Updates

We've added a comprehensive guide for managing sessions and permissions, and updated our core concepts documentation with important clarifications.

What's New​

New Guide: Managing Sessions and Permissions​

We've added a new quick start guide: Managing sessions and permissions. This guide provides step-by-step instructions for:

  • Detecting permission changes using webhooks and session comparison
  • Handling session deletion and revocation
  • Communicating permission changes to players
  • Implementing permission upgrade flows
  • Understanding how challenges relate to sessions

This guide is essential for any integration that needs to respond to permission changes over time, such as when parents modify settings or players age up.

Documentation Updates​

Sessions Documentation​

The Sessions concept page has been updated with important clarifications:

  • Session ID persistence: Players have exactly one session per product. The session ID persists through permission changes, but a new session ID is created if a session is revoked and the consent flow is completed again.
  • Session deletion behavior: Deleted sessions return HTTP 400 with NOT_FOUND error code (not 404). This is intentional—deleted sessions should be treated as if they never existed.
  • Age-up changes: Age-up events don't trigger webhook notifications. You must use session comparison to detect these changes.

Permissions Documentation​

The Permissions concept page has been enhanced with:

  • managedBy field changes: Clarified that managedBy can change over time (for example, from GUARDIAN to PLAYER when a player ages up).
  • Player-managed permissions: When a player requests to enable a PLAYER-managed permission via the /session/upgrade API, it's automatically enabled without creating a challenge.
  • Permissions upgrade content: The permissions upgrade documentation has been merged into the Permissions page for better discoverability.

What Changed​

Merged Documentation​

  • The Permissions upgrade concept page has been merged into the Permissions page. All references have been updated to point to the new location.

Next Steps​

If you have any questions about these updates or need assistance with your integration, please don't hesitate to reach out to our support team.

Developer Role and Product Access Control

We've introduced a new Developer role in Compliance Studio with product-level access control, enabling organizations to maintain clear boundaries between different products and teams.

What's New​

Developer Role​

A new Developer role is now available in Compliance Studio. Users with the Developer role can manage products and product developer settings, but only for products they have been explicitly assigned to.

Key Features:​

  • Product-level access control: Developers can be restricted to access only specific products within your organization
  • Granular permissions: Each Developer role member can be assigned to their respective products, enabling product-level access control and maintaining organizational boundaries
  • Product management: Developers can manage products and product developer settings for their assigned products only

Member Access Management​

A new Member Access menu has been added to the Organization settings, allowing Owners and Admins to assign product access to members with the Developer role.

How it works:​

  • Access assignment: Owners and Admins can use the Member Access menu to assign specific products to Developer role members
  • Multiple product assignment: You can assign multiple products to a single Developer
  • Immediate effect: Product access assignments take effect immediately

Updated Documentation​

Edge Case Handling Examples

We've added comprehensive edge case handling examples to the age verification guide and updated the verification event contract to clarify field presence rules.

What's New​

Edge Case Handling Examples​

The Waterfall Flow guide now includes detailed code examples for handling verification edge cases. Each example demonstrates both incorrect and correct handling patterns.

New examples include:​

  • Partial attempt (max attempts exceeded): Proper handling of max-attempts-exceeded failure reason when users exhaust all verification attempts without a conclusive age determination
  • Suspicious activity detected: Security-focused handling of fraudulent-activity-detected failure reason, including appropriate rate limiting and security measures
  • Complete edge case handler: A comprehensive TypeScript example demonstrating all patterns together

All examples link directly to the Verification Event Contract for complete field presence rules.

Verification Event Contract Updates​

The Verification Event Contract has been updated to clarify field presence rules:

  • age and ageCategory are always present for PASS status: All verification methods that result in PASS provide both age information and age category. You can safely access these fields without conditional checks when processing PASS status results.
  • Age bounds clarification: When an exact age is not provided by the verification method, age.low will be the threshold minimum age required for the verification, and age.high will be 100.

Updated Documentation​

Mobile App Integration Guide and ConnectID Testing Updates

We've added comprehensive mobile app integration documentation and enhanced ConnectID testing resources to help you integrate k-ID widgets into mobile applications.

What's New​

Mobile App Integration Guide​

A new Mobile Apps quick start guide provides comprehensive documentation for integrating k-ID widgets into mobile applications. The guide covers:

  • Platform-specific implementation methods: Detailed guidance for Android (Custom Tabs, WebView, Trusted Web Activity) and iOS (ASWebAuthenticationSession, SFSafariViewController, WKWebView)
  • AgeKeys support: Clear documentation on which implementation methods support AgeKeys and WebAuthn
  • Result communication: Two approaches for receiving widget results—callback URLs (recommended) and DOM messages
  • Third-party app verification flows: Complete documentation on how verification methods like ConnectID redirect through third-party apps
  • Complete code examples: Step-by-step implementation examples for both iOS (Swift) and Android (Kotlin) with full code samples

ConnectID Testing Enhancements​

Enhanced ConnectID testing documentation with mobile app testing resources:

  • Mobile app test apps: Added links to ConnectID Mock Bank C test apps for iOS (TestFlight) and Android (Google Play) to validate the complete redirect flow in mobile applications
  • Testing section updates: Expanded the ConnectID testing section with a dedicated subsection for mobile app redirect flow testing

Updated Documentation​

Introducing the Changelog

We're excited to introduce our new Changelog section! This will serve as a centralized place to keep you updated on changes to developer interfaces, API behaviors, and integration patterns.

What's New​

Changelog Section​

Starting today, you can find updates about developer-facing changes in one convenient location. We'll be posting regular updates here to help you stay informed about:

  • API updates and changes: New endpoints, parameter modifications, and deprecations
  • Event system updates: Changes to DOM events and webhooks
  • Interface and behavior changes: Updates to developer interfaces and integration patterns
  • Breaking changes: Important updates that may affect your integration

Verification Event Contract​

We're introducing the Verification Event Contract to provide developers with reliable reference material for how all verification result data is expected to be formatted. This contract applies to both DOM Events and Webhooks, and we're committed to maintaining it as a stable reference for your integrations.

What this means:​

  • Consistent event structure: Predictable event payloads across all event types
  • Comprehensive documentation: Complete event schemas and examples for easier integration
  • Reliable reference: We're committed to maintaining this contract as stable reference material for verification result data formatting

For detailed information about the event structures and how to use them in your integration, please refer to our Events documentation.

Stay Updated​

Bookmark this changelog and check back regularly, or subscribe to our updates to stay informed about the latest changes to the k-ID platform. We're committed to keeping you informed about all updates that may impact your integration.

For high-level product announcements and feature releases, see our Release Notes.

Subscribe to Updates​

You can subscribe to the changelog using your preferred feed format:

Add any of these feed URLs to your RSS reader, news aggregator, or monitoring tool to receive automatic notifications when new changelog entries are published.