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/upgradeenables 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 threshold | Age verified? | managedBy | enabled |
|---|---|---|---|
| Below the minimum age | N/A | PROHIBITED | false |
| At or above the minimum age, below the threshold | N/A | GUARDIAN | true only after a guardian consents |
| At or above the threshold | No | PLAYER | false, unless a guardian enabled it before the user reached the threshold |
| At or above the threshold | Yes, through a verified platform signal | PLAYER | true |
| At or above the threshold | Yes, through age assurance | PLAYER | true |
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:
| Field | Type | Description |
|---|---|---|
platformAgeSignal | PlatformAgeSignal | A platform signal that can satisfy the threshold immediately |
options | object | Options forwarded into the age assurance experience |
options.facialAgeEstimation.passIfOver | integer | Minimum age at which facial age estimation should pass. Leave it unset to use k-ID's defaults; see Facial age estimation margins. |
options.facialAgeEstimation.failIfUnder | integer | Facial 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.redirectUrl | string | Redirect 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
verifiedAgeThresholdor all not have one. A request that mixes the two returns400. - 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_UPGRADEchallenge for theGUARDIANpermissions that aren't enabled yet.PROHIBITEDpermissions 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
materialChangeand legal document options work on that guardian path as in the standard flow. On the age-assurance path, they return400- A verified platform signal can satisfy some or all requested permissions immediately
- An existing
ageVerificationon 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_UPGRADEpoints tohttps://family.k-id.com/authorize?otp=.... The guardian approves there, and completion follows the standard upgrade flow.CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCEpoints tohttps://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:
- The token is parsed and validated.
- If the challenge is already resolved, the user is redirected to the completion page.
- 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).
- 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-ef1234567890Possible 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"
}
}| Field | Description |
|---|---|
data.id | The challengeId returned by POST /session/upgrade |
data.status | PASS, FAIL, or IN_PROGRESS |
data.type | The challenge type (for example, CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE) |
data.sessionId | Present 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, fetchGET /session/getand use the refreshed permissions. The permissions the check proved are now enabled, and the session containsageVerification. - After
FAIL, the permission remains disabled. The user can retry later through anotherPOST /session/upgradecall.
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
- Direct the user to an age appeal. Call
POST /age-verification/perform-age-appealwith the appropriatejurisdictionandcriteria. 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. - 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
verificationIdthat 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.
- On success: The appeal produces a
- Invalidate the session. After a successful appeal, delete the old session with
POST /session/deleteand discard itssessionId. - Restart the age gate flow with the k-ID signal. Send the
verificationIdfrom the appeal as ak-idplatform 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