Get startedQuick start guides

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

  1. A CDK product in Compliance Studio with the features your product gates registered as permissions. See Product configuration: API configuration.
  2. 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.
  3. A webhook endpoint that receives Challenge.StateChange and Session.ChangePermissions events. See Webhooks.
  4. 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:

  1. In Compliance Studio, open your product and select Engine & Overrides.
  2. Select Edit Global Rules.
  3. Under Feature-level access, choose Yes to apply the CDK's rules to every feature, or Yes, with changes to override individual features.
  4. 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:

PermissionWhat you show
enabled: trueThe feature, unlocked
managedBy: "PLAYER", verifiedAgeThreshold present, enabled: falseThe 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"
  }
}
statusWhat you do
PASSContinue to Step 7. When the check changed the session's permissions, k-ID also sends Session.ChangePermissions.
FAILThe feature stays locked. The user can try again later through another /session/upgrade call.
IN_PROGRESSKeep 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 verifiedAgeThreshold and enabled: false
  • call /session/upgrade and complete the check from the challenge URL (test mode challenge URLs expire after 7 minutes)
  • confirm your webhook receives Challenge.StateChange with status: PASS
  • confirm /session/get returns the permission with enabled: true and the session has ageVerification
  • call /session/upgrade again for the same permission and confirm no challenge is returned

What's next?

On this page