CDKAdaptive Access

Feature-level age assurance

How CDK asks a user to prove their age when they reach a protected feature, and how the permission unlocks afterward.

Feature-level age assurance is the part of Adaptive Access that asks for proof of age when a user reaches a protected feature, not at sign-up. Some permissions in some markets need a verified age before they can be enabled, such as paid loot boxes or targeted ads where a market's rules require it. At or above the threshold, these permissions stay disabled until the user proves their age, either with a platform age signal that counts as verified, or with a CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE challenge from POST /session/upgrade. When a permission's minimum age is below its threshold, a parent or guardian can consent for a user who is at or above the minimum age but below the threshold. When the minimum age is the same as the threshold, no guardian can consent, and a user below the threshold can't get the permission.

For a step-by-step integration, see the Age assurance at features quick start.

What this page helps you do

Use this page when you need to understand:

  • Why a permission is still disabled after the user has already passed the age gate
  • Whether POST /session/upgrade enables a permission immediately or returns a challenge
  • How to handle a user who meets the threshold but hasn't verified their age yet
  • How to recover when a user originally claimed an age below the minimum age

Turning it on

Feature-level age assurance is controlled by Feature-level access in Compliance Studio, under Engine & Overrides > Edit Global Rules, and can be changed per market. New products start with it set to Yes. Existing products show No until you change it. See Configure Adaptive Access.

With Feature-level access set to No for a market, configurations you publish from Compliance Studio give no permission in that market a verifiedAgeThreshold, even where the CDK's rules call for one.

Verified age threshold

A verifiedAgeThreshold means the permission needs a verified age, not just a claimed or inferred age. Which permissions have one, and at what age, comes from the CDK's rules for the user's market and any overrides you set in Compliance Studio. Read the threshold from the session, or from /age-gate/get-requirements, which lists every permission with a verifiedAgeThreshold for the market under permissions. Don't hard-code thresholds in your app.

For a permission with a verifiedAgeThreshold:

  • Below the permission's minimum age, the permission is managedBy: PROHIBITED.
  • At or above the minimum age and below the threshold, the permission is managedBy: GUARDIAN. A parent or guardian can consent to it through the standard guardian consent flow, not age assurance.
  • At or above the threshold, the permission is managedBy: PLAYER, and stays disabled until the user verifies, unless a guardian enabled it before the user reached the threshold.

When a permission's minimum age is the same as its threshold, the permission is never managedBy: GUARDIAN: below the threshold it's PROHIBITED.

Permission state logic

When a permission has a verifiedAgeThreshold, the Permission object includes that field:

{
  "name": "loot-boxes-paid-gameplay-impacting",
  "enabled": false,
  "managedBy": "PLAYER",
  "verifiedAgeThreshold": 18
}
User age compared to thresholdAge verified?managedByenabled
Below the minimum ageN/APROHIBITEDfalse
At or above the minimum age, below the thresholdN/AGUARDIANtrue only after a guardian consents
At or above the thresholdNoPLAYERfalse, unless a guardian enabled it before the user reached the threshold
At or above the thresholdYes, through a verified platform signalPLAYERtrue
At or above the thresholdYes, through age assurancePLAYERtrue

Guardian consent unlocks a threshold permission only while the user is below the threshold. At or above the threshold, guardian consent doesn't replace a verified age, but a permission that a guardian enabled earlier stays enabled.

ageVerification on the session

When a verified platform signal is processed or an age assurance challenge completes, the session stores an ageVerification object:

{
  "ageVerification": {
    "verifiedAge": 18,
    "platformName": "apple-ios",
    "declarationType": "governmentIDChecked",
    "verifiedAt": "2026-03-14T00:00:00Z"
  }
}

This verification is reusable. Once it's on the session, a later POST /session/upgrade for a permission with the same or a lower threshold is granted without a new challenge.

Session upgrade flow

POST /session/upgrade decides whether the user can get the permission immediately or needs to verify first.

Session upgrade API

Relevant request fields:

FieldTypeDescription
platformAgeSignalPlatformAgeSignalA platform signal that can satisfy the threshold immediately
optionsobjectOptions forwarded into the age assurance experience
options.facialAgeEstimation.passIfOverintegerMinimum age at which facial age estimation should pass. Leave it unset to use k-ID's defaults; see Facial age estimation margins.
options.facialAgeEstimation.failIfUnderintegerFacial age estimation fails only when the whole estimated age range is below this age. A range that overlaps it is inconclusive, and the user can try another method
options.redirectUrlstringRedirect target after the challenge completes, when it runs in a top-level browser context (not an iframe). Accepts http(s) and custom-scheme mobile deep links (for example myapp://upgrade/return); unsafe schemes are rejected and no redirect occurs. On completion k-ID appends challengeId, productId, sessionId (present only on PASS), status (PASS or FAIL), and type. Confirm the outcome server-side; treat the query parameters as a UX hint.

Example request (verified platform signal satisfies the permission):

POST /api/v1/session/upgrade

{
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ],
  "platformAgeSignal": {
    "name": "apple-ios",
    "ageLow": 18,
    "ageHigh": 25,
    "declarationType": "governmentIDChecked"
  }
}
{
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "permissions": [
      {
        "name": "loot-boxes-paid-gameplay-impacting",
        "enabled": true,
        "managedBy": "PLAYER",
        "verifiedAgeThreshold": 18
      }
    ],
    "ageVerification": {
      "verifiedAge": 18,
      "platformName": "apple-ios",
      "declarationType": "governmentIDChecked",
      "verifiedAt": "2026-03-14T00:00:00Z"
    }
  }
}

Example request (user meets the threshold but still needs age assurance):

POST /api/v1/session/upgrade

{
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ],
  "options": {
    "redirectUrl": "https://mygame.com/callback"
  }
}
{
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "permissions": [
      {
        "name": "loot-boxes-paid-gameplay-impacting",
        "enabled": false,
        "managedBy": "PLAYER",
        "verifiedAgeThreshold": 18
      }
    ]
  },
  "challenge": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE",
    "url": "https://family.k-id.com/session/upgrade/age-assurance?token=..."
  }
}

Example outcome (user is below the permission's minimum age):

{
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "permissions": [
      {
        "name": "loot-boxes-paid-gameplay-impacting",
        "enabled": false,
        "managedBy": "PROHIBITED",
        "verifiedAgeThreshold": 18
      }
    ]
  }
}

In this case, no challenge is returned because neither the user nor a guardian can enable the permission at this age.

Example outcome (user is below the threshold, at or above the minimum age):

This example uses a product where multiplayer has a minimum age of 13 and a threshold of 18, and the user is 15.

{
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "permissions": [
      {
        "name": "multiplayer",
        "enabled": false,
        "managedBy": "GUARDIAN",
        "verifiedAgeThreshold": 18
      }
    ]
  },
  "challenge": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_SESSION_UPGRADE",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

This is the same guardian challenge as in the standard upgrade flow. The permission turns on when the guardian approves. No age assurance runs.

Key behaviors:

  • The requested permissions must either all have a verifiedAgeThreshold or all not have one. A request that mixes the two returns 400.
  • If the user is below the Digital Consent Age, the request uses the standard guardian consent flow instead of age assurance
  • If the user is below every requested threshold, the request goes to the guardian: the response has a CHALLENGE_SESSION_UPGRADE challenge for the GUARDIAN permissions that aren't enabled yet. PROHIBITED permissions are left out. If no permission is left and the request has no legal documents or acceptance deadline, no challenge is issued
  • The session's age decides whether the user is below every requested threshold. A platform age is read on this guardian path and on the age-assurance path. It does not move a request from one of those paths to the other. On the guardian path, a permission is left out of the challenge when the platform age is below its minimum age. On the age-assurance path, it is left out when the platform age is below its threshold. A request below the Digital Consent Age, a request with age assurance turned off, and a Safe Start upgrade do not read a platform age
  • If the session age meets at least one requested threshold, the request goes to age assurance. Requested permissions that the user is still below the threshold for are left out, and no guardian challenge is issued for them. To ask a guardian for those, request them in a separate call
  • materialChange and legal document options work on that guardian path as in the standard flow. On the age-assurance path, they return 400
  • A verified platform signal can satisfy some or all requested permissions immediately
  • An existing ageVerification on the session can also satisfy the request
  • Only the permissions still unresolved turn into an age assurance challenge

Requesting permissions at different ages

You can request permissions with different thresholds in one call, for example a 16+ feature and an 18+ feature. The challenge asks about the highest requested age, and the user verifies once. When the check passes, every requested permission is enabled. When it fails, none are: a user whose ID document shows they're 17 gets neither the 16+ nor the 18+ permission from that call. To let a lower-age feature unlock on its own, request it in a separate call.

A session upgrade only enables permissions you requested. It never enables a permission you didn't ask for, and never disables one.

Handling the challenge result

The challenge URL depends on the challenge type.

  • CHALLENGE_SESSION_UPGRADE points to https://family.k-id.com/authorize?otp=.... The guardian approves there, and completion follows the standard upgrade flow.
  • CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE points to https://family.k-id.com/session/upgrade/age-assurance?token=.... The steps below are for this type.

The URL's expiry is encoded as the exp claim of the JWT in the token query parameter. In live mode, challenge URLs are valid for 2 weeks by default, though some jurisdictions are shorter (for example Indonesia, where parental-consent challenges expire 24 hours after creation). In test mode, they're valid for only 7 minutes so you can exercise expired-URL handling without waiting. For more, see Challenge URL and email link expiration.

When the user opens this URL:

  1. The token is parsed and validated.
  2. If the challenge is already resolved, the user is redirected to the completion page.
  3. If still pending, a verification iframe shows the age assurance methods configured for your product (such as facial age estimation or an ID document scan).
  4. On completion, the result is communicated back to your integration.

You can receive that result in three ways:

Option 1: Listen for postMessage

For iframe or webview integrations, the challenge page posts a Challenge.StateChange message to the parent window:

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "your-product-id",
    "status": "PASS",
    "type": "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE"
  }
}

Warning

DOM postMessage events are useful for updating your UI, but they aren't authoritative. Use a webhook or the polling endpoint for any server-side logic.

Option 2: Poll GET /challenge/get-status

GET /api/v1/challenge/get-status?challengeId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Possible statuses are PASS, FAIL, PENDING, and IN_PROGRESS.

Option 3: Receive a Challenge.StateChange webhook

k-ID posts a Challenge.StateChange webhook event to your configured endpoint whenever the challenge status changes:

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": 11472,
    "status": "PASS",
    "type": "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE",
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
  }
}
FieldDescription
data.idThe challengeId returned by POST /session/upgrade
data.statusPASS, FAIL, or IN_PROGRESS
data.typeThe challenge type (for example, CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE)
data.sessionIdPresent on PASS: use this to fetch the refreshed session

When a passed check changes the session's permissions, k-ID also sends a Session.ChangePermissions webhook for the session.

Webhooks are the recommended approach for server-side handling because they're delivered in real time and don't require polling. For the full field reference and status lifecycle, see Challenge.StateChange.

After the result

  • After PASS, fetch GET /session/get and use the refreshed permissions. The permissions the check proved are now enabled, and the session contains ageVerification.
  • After FAIL, the permission remains disabled. The user can retry later through another POST /session/upgrade call.

Recovery flow for a user who entered an age below the minimum age

Sometimes a user enters a claimed age below a permission's minimum age and ends up with a PROHIBITED permission. In that case, the normal session/upgrade flow can't fix the problem because the session already says the user is too young for that feature.

This recovery flow is for:

  • Player-managed sessions
  • Guardian-managed sessions that don't yet have an approver linked

It's not the right flow when the session is guardian-managed and already has an approver.

Recovery steps

  1. Direct the user to an age appeal. Call POST /age-verification/perform-age-appeal with the appropriate jurisdiction and criteria. Present the returned URL in the surface appropriate for your app (web iframe, pop-up, or redirect; a system browser on mobile; an in-app browser surface; or a QR code handoff on consoles) for the user to complete age verification. See the Mobile apps quick start for mobile details. Don't invalidate the session yet: if the appeal fails, the user keeps their existing session and won't need to go through VPC again.
  2. Handle the age appeal result. Listen for the result through DOM events, webhooks, or GET /age-verification/get-status.
    • On success: The appeal produces a verificationId that proves the user's verified age.
    • On failure: The feature remains prohibited. The user stays at their originally claimed age, and the existing session is preserved.
  3. Invalidate the session. After a successful appeal, delete the old session with POST /session/delete and discard its sessionId.
  4. Restart the age gate flow with the k-ID signal. Send the verificationId from the appeal as a k-id platform signal, without the user's earlier age or date of birth. A platform signal never verifies above the age the user declared, so an earlier, lower age would win.
POST /api/v1/age-gate/check

{
  "jurisdiction": "BR",
  "platformAgeSignal": {
    "name": "k-id",
    "verificationId": "<verificationId from age appeal>"
  }
}

k-ID resolves the verified age from the verificationId. If the verified age meets or exceeds the verifiedAgeThreshold, the session is created with the permission enabled.

Sequential permission upgrades

Each threshold permission is tracked independently:

  • Upgrading one permission doesn't automatically upgrade another
  • Each permission still needs to be requested through POST /session/upgrade
  • Once the session has an ageVerification, later permissions with the same or a lower threshold are granted without another challenge

On this page