Skip to main content

Challenges

A Consent Challenge is created when a child seeks consent for access to a game or game feature. The challenge is displayed as a Request for Access to the trusted adult in k-ID Family Connect once a verified trusted adult is associated with the Consent Challenge.

What's a challenge?​

A consent challenge represents a player's request for parental consent. When a player's age requires Verifiable Parental Consent (VPC) in the current jurisdiction, k-ID creates a challenge that must be approved by a trusted adult before the player can access the game or feature.

Challenge creation​

Challenges are created automatically when:

  • A player's age requires parental consent (determined by the /age-gate/check API)
  • A player requests access to a permission that requires guardian consent (via the /session/upgrade API)

The challenge ID is returned in the API response and should be stored by the game in local storage or cloud storage associated with the player.

Challenge information​

When a challenge is created, the API returns:

  • challengeId: A unique identifier for the challenge
  • oneTimePassword: A password that can be entered by a parent to access the consent portal
  • url: A URL that can be rendered as a QR code for easy mobile access

The consent challenge window should show the QR code, one time password, and an input field to allow the player to enter the email address of a parent or guardian who can grant consent.

Challenge

Challenge status​

After showing the consent challenge window, the game should wait until the challenge has been completed successfully. It's strongly recommended to use Webhooks, listening for the Challenge.StateChange event. As a fallback option, polling is available by calling the /challenge/get-status API periodically with the challenge ID.

The challenge status can be:

  • PASS: Consent has been granted by a trusted adult
  • FAIL: The request was denied
  • PENDING: The challenge is still waiting for a response
  • POLL_TIMEOUT: The polling timeout has been reached (when using polling with timeout)

Notifying trusted adults​

There are several ways to notify trusted adults about a consent challenge:

QR code and one-time password​

The challenge response includes a URL that can be rendered as a QR code and a one-time password. Parents can use either method to access the consent portal directly.

Email notification​

If an email address for a parent or guardian is provided by the player, the game should pass this email address as a parameter to the /challenge/send-email API, which sends a pre-configured email to the address with a link that leads a parent to Family Connect where they can approve. Configuration options for this email are provided in the Compliance Studio.

The game must determine how long to wait for consent to be granted and what to do if that time expires. The choice of duration could be short (10 minutes) or longer (24 hours or more).

There might be many calls made to the /challenge/get-status API during this time. Between calls to /challenge/get-status, there should be a minimum of 5 seconds delay. Also, /challenge/get-status can return HTTP code 429. The game should implement appropriate retry logic when handling 429 responses.

For some games, it's appropriate to stop the player from continuing at all in the game until a parent grants consent, and the window should be modal. In other games, it might be reasonable that an underage player is allowed to continue for a certain amount of time before being denied access while trusted adult consent is requested. In this case, while waiting for trusted adult consent, the game is responsible to avoid collecting data about the player, or giving access to other functions that might require consent.

When a status of CHALLENGE is returned from /age-gate/check, the returned challenge ID should be stored in local storage while the challenge is active. The presence of an active challenge when the game starts directs the game to show the same consent challenge window from before. After retrieving the challenge ID from local storage, the /challenge/get API should be invoked to retrieve information about the current challenge, including the one time password and QR code URL, and the challenge window should again be displayed to the user.

Challenge expiration and time-based authentication​

Although the consent challenge itself doesn't expire, the generated time-based authentication methods do (for example, OTP, email link). k-ID implements time-based authentication mechanisms to ensure security while maintaining usability.

One-time passwords (OTPs)​

Each challenge creates a unique OTP that parents can use to access the consent portal. These OTPs are:

  • Generated automatically when a challenge is created
  • Valid for 1 hour
  • Refreshed through the /challenge/generate-otp API

QR code URLs​

The challenge response includes a URL that can be rendered as a QR code for easy mobile access. This URL:

  • Contains embedded OTP
  • Expires alongside the OTP (1 hour)
  • Provides a seamless mobile experience for parents

When using the /challenge/send-email API to send consent requests:

  • Email links expire after two weeks
  • Links contain cryptographically signed tokens
  • Expired links require generating new email requests

Best practices​

When implementing k-ID's time-based authentication:

  1. Monitor expiration proactively, rather than reactively
  2. Implement graceful degradation when credentials expire
  3. Provide clear user feedback about timeout status
  4. Test timeout scenarios thoroughly in test environments
  5. Plan for edge cases such as network interruptions during refresh operations

Getting the trusted adult email address​

If consent is granted, the email address of the parent is returned in the approverEmail field in the response from /challenge/get-status. This can be stored by the game for use in future customer service cases.

Testing challenges​

It's possible to test trusted adult consent in the API without going through the trusted adult consent flow in Family Connect. To do this, you can call /test/set-challenge-status to set the status of the consent challenge. You can assign the status to PASS or FAIL. You must also pass the age and jurisdiction as part of the body. Optionally you can pass an email to return in the approverEmail field. The next call to /challenge/get-status using the same challengeId returns the information you assigned. This allows you to rapidly test trusted adult consent scenarios in your game.