Age assurance at features
Ask users to prove their age only when they reach a protected feature, with Adaptive Access and /session/upgrade.
This guide sets up feature-level age assurance, the feature half of Adaptive Access. Users sign up normally. When a user reaches a feature that needs a verified age in their market, your app asks k-ID to unlock it, and the user proves their age only if they haven't already. You'll go from the Compliance Studio setting to an unlocked feature in one path: settings, the session, the check, the result, and the feature unlock.
To ask for proof at sign-up instead, follow Age assurance at entry.
Integrate with AI coding agents
Official Agent Skills cover sessions, permissions, age assurance challenges, and webhooks for AI-assisted integration.
Prerequisites
- A CDK product in Compliance Studio with the features your product gates registered as permissions. See Product configuration: API configuration.
- A test mode API key from your product's Developer Settings. Test mode calls go to
https://game-api.test.k-id.com. See Testing. - A webhook endpoint that receives
Challenge.StateChangeandSession.ChangePermissionsevents. See Webhooks. - A CDK session for the user, from the custom age gate, the VPC widget, or age assurance at entry.
Keep your API key on your server
Every k-ID API call in this guide is server-to-server. Never send your API key to a browser or app.
Step 1: Turn on feature-level access
New products start with feature-level access set to Yes. For an existing product, or to check yours:
- In Compliance Studio, open your product and select Engine & Overrides.
- Select Edit Global Rules.
- Under Feature-level access, choose Yes to apply the CDK's rules to every feature, or Yes, with changes to override individual features.
- Select Save changes, then Push to Test.
See Configure Adaptive Access for per-feature and per-market rules.
Step 2: Find the features that need a verified age
Read the user's session with GET /session/get. A permission that needs a verified age carries a verifiedAgeThreshold:
{
"sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
"permissions": [
{
"name": "loot-boxes-paid-gameplay-impacting",
"enabled": false,
"managedBy": "PLAYER",
"verifiedAgeThreshold": 18
}
]
}Decide how to show each feature from the permission alone:
| Permission | What you show |
|---|---|
enabled: true | The feature, unlocked |
managedBy: "PLAYER", verifiedAgeThreshold present, enabled: false | The feature, with a prompt to verify age to unlock it |
managedBy: "PROHIBITED" | Nothing. The user is below the permission's minimum age, and no check can unlock it. |
managedBy: "GUARDIAN" | The feature, with a prompt to ask a parent. A parent or guardian can consent when the user is at or above the permission's minimum age and below its threshold; see Managing sessions and permissions. |
Don't hard-code thresholds or markets. They come from the CDK's rules for the user's market and your Compliance Studio settings, and can change without a code change.
Step 3: Ask k-ID to unlock the feature
When the user chooses the feature, call POST /session/upgrade from your server with that permission. Include a redirect URL if the check will open outside an iframe. If you have a platform age signal, include it too; a trustworthy one at or above the threshold unlocks the feature without a check.
POST /api/v1/session/upgrade
Content-Type: application/json
Authorization: Bearer your-api-key
{
"sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
"requestedPermissions": [
{ "name": "loot-boxes-paid-gameplay-impacting" }
],
"options": {
"redirectUrl": "https://mygame.com/upgrade/return"
}
}Request only permissions that have a verifiedAgeThreshold in this call. A request that mixes permissions with and without one returns 400.
You can request several threshold permissions at once, even at different ages. The user verifies once. The check is judged at the highest requested age, so either every requested permission unlocks or none does. See Requesting permissions at different ages.
Step 4: Handle the response
The response always contains the session, and contains a challenge only when the user must verify or a parent or guardian must approve:
const result = await response.json();
if (!result.challenge) {
// No check needed: a platform signal or the session's existing
// ageVerification already proved the age, or no requested permission can
// be unlocked at the user's age. Read each permission's `enabled` value from
// result.session.
return unlockFrom(result.session);
}
if (result.challenge.type === "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE") {
await saveChallenge(result.challenge.challengeId, result.session.sessionId);
return showAgeCheck(result.challenge.url);
}
if (result.challenge.type === "CHALLENGE_SESSION_UPGRADE") {
// The user is below every requested threshold or below the digital consent age, so a parent or guardian approves.
await saveChallenge(result.challenge.challengeId, result.session.sessionId);
return showParentApproval(result.challenge.url);
}An age assurance challenge looks like this:
{
"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=..."
}
}Step 5: Show the check
Show challenge.url to the user, not to a parent. The user verifies with one of your product's age assurance methods.
On the web, embed it in an iframe. The allow attribute is required for the camera, payment, and AgeKey methods:
<iframe
src="CHALLENGE_URL"
width="100%"
height="600"
frameborder="0"
allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
</iframe>On mobile, open the URL in a system browser and handle the redirect URL from Step 3. See the Mobile apps quick start. On consoles, show the URL as a QR code for the user's phone.
The page posts a Challenge.StateChange message to the parent window when the user finishes. Use it to close the iframe, not to unlock the feature.
Step 6: Get the result on your server
Read the result from k-ID on your server, with the Challenge.StateChange webhook or by polling GET /challenge/get-status:
{
"eventType": "Challenge.StateChange",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"productId": 42,
"type": "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE",
"status": "PASS",
"sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
}
}status | What you do |
|---|---|
PASS | Continue to Step 7. When the check changed the session's permissions, k-ID also sends Session.ChangePermissions. |
FAIL | The feature stays locked. The user can try again later through another /session/upgrade call. |
IN_PROGRESS | Keep waiting. |
Step 7: Unlock the feature
Call GET /session/get and turn the feature on only if its permission now has enabled: true. Don't unlock features from the challenge status alone.
The session now includes ageVerification. A later /session/upgrade for a feature at the same or a lower age is granted without another check, so the user proves their age once.
Step 8: Test it
In test mode, create a session for a user old enough for a protected feature in a market where the CDK requires a verified age, then:
- confirm the permission has
verifiedAgeThresholdandenabled: false - call
/session/upgradeand complete the check from the challenge URL (test mode challenge URLs expire after 7 minutes) - confirm your webhook receives
Challenge.StateChangewithstatus: PASS - confirm
/session/getreturns the permission withenabled: trueand the session hasageVerification - call
/session/upgradeagain for the same permission and confirm no challenge is returned
What's next?
- Feature-level age assurance: the full reference, including the recovery flow for users who entered an age below a threshold
- How verification works: methods, facial age estimation margins, and what the session records
- Managing sessions and permissions: keep permissions in sync as they change
- Pre-launch checklist