Skip to main content

Challenges

When a player's age requires Verifiable Parental Consent (VPC), k-ID creates a consent 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 calling /age-gate/check with a date of birth that requires parental consent. The challenge information is returned in the response:

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

Challenge information​

When a challenge is created, you receive:

  • challengeId: A unique identifier for the challenge (store this for later use)
  • 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

Displaying the challenge​

For information about displaying challenges and what information to show, see Challenges in the Core concepts section.

Notifying trusted adults​

There are several ways to notify trusted adults about a consent challenge. For detailed information about notification methods, see Challenges in the Core concepts section.

Email notification​

If an email address for a parent or guardian is provided by the player, call /challenge/send-email with the challenge ID and email address:

POST /api/v1/challenge/send-email
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
  "email": "parent@example.com"
}

Alternatively, you can call /challenge/send-email without specifying an email address, and the API sends an email to the trusted adult who most recently approved a permission for the player. If no associated email address is found, the API responds with an INVALID_EMAIL error code.

Checking challenge status​

After showing the consent challenge, wait for the trusted adult to complete the consent process. You can check the challenge status in two ways:

For detailed information about the webhook event structure, see Challenge.StateChange.

Configure a webhook endpoint to receive Challenge.StateChange events. For more information, see Webhooks.

Polling​

Poll the /challenge/get-status API periodically with the challenge ID:

GET /api/v1/challenge/get-status?challengeId=683409f1-2930-4132-89ad-827462eed9af
Authorization: Bearer your-api-key

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)

Example PASS response​

{
  "status": "PASS",
  "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
  "approverEmail": "parent@example.com"
}

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 more information about waiting for consent and how long to wait, see Challenges in the Core concepts section.

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.

For more information, see Challenges in the Core concepts section.

Challenge expiration​

Although the consent challenge itself doesn't expire, the generated time-based authentication methods do (for example, OTP, email link). For more detail on how k-ID uses time-based authentication within user flows, see Challenges.

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.

For more information about challenges, including testing challenges, see Challenges in the Core concepts section.