Get startedQuick start guides

Age assurance at entry

Ask users to prove their age at the age gate with Adaptive Access, and create their CDK session only after they pass.

This guide sets up product-level age assurance, the entry half of Adaptive Access. Users who claim an age at or above the trigger age you choose prove it before they get a session. You'll go from the Compliance Studio setting to an unlocked session in one path: settings, the age gate result, the check, the result, and the session.

To ask for proof only when users reach specific features, follow Age assurance at features instead. Many products only need that one.

Integrate with AI coding agents

Official Agent Skills cover the age gate, age assurance challenges, and webhooks for AI-assisted integration.

Prerequisites

  1. A CDK product in Compliance Studio. See Creating a product.
  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 events. See Webhooks.
  4. An age gate that collects the user's age or date of birth. To build your own, follow Custom age gate. If you use the age gate or end-to-end widget, the widget runs the check for you and reports the result in Widget.AgeGate.Result.

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 product-level access

  1. In Compliance Studio, open your product and select Engine & Overrides.
  2. Select Edit Global Rules.
  3. Under Product-level access, choose Yes.
  4. Under Who this applies to, choose the trigger age. Civil Age is the default.
  5. Select Save changes, then Push to Test.

To turn it on for some markets only, leave the global answer at No and set Yes for those markets with Add Market Specific Rules. See Configure Adaptive Access.

Step 2: Check the user's age

After your age gate collects the user's age, call POST /age-gate/check from your server. Include a redirect URL if the check will open outside an iframe, such as in a system browser on mobile.

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "dateOfBirth": "2001-04-15",
  "options": {
    "playerAgeAssurance": {
      "redirectUrl": "https://mygame.com/age-gate/return"
    }
  }
}

If you have a platform age signal, send it as platformAgeSignal. A trustworthy signal at or above the trigger age skips the check.

Step 3: Handle the age gate result

Branch on status, and for CHALLENGE, on challenge.type:

ResponseWhat it meansWhat you do
PASSNo check is needed for this userStore session.sessionId and continue
PROHIBITEDThe user is below the product's minimum ageBlock the user
CHALLENGE with CHALLENGE_PARENTAL_CONSENTThe user needs parental consentFollow Custom age gate
CHALLENGE with CHALLENGE_AGE_GATE_AGE_ASSURANCEThe user must prove their ageContinue to Step 4

An age assurance challenge looks like this. No session is returned yet:

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "CHALLENGE_AGE_GATE_AGE_ASSURANCE",
    "url": "https://family.k-id.com/age-gate/verify?token=..."
  }
}

Store challengeId on your server so you can match the result to this user.

Branch on the response, not on `ageAssuranceRequired`

ageAssuranceRequired from /age-gate/get-requirements is a reporting value. It doesn't tell you whether this challenge will be returned.

Step 4: Show the check

Send challenge.url to your client and show it to the user. The user verifies themselves 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 2. See the Mobile apps quick start. On consoles, show the URL as a QR code for the user's phone.

To close the iframe when the user finishes, listen for the Verification.Result message:

window.addEventListener("message", (event) => {
  if (!event.origin.endsWith(".k-id.com")) return;
  if (event.data?.eventType === "Verification.Result") {
    closeAgeAssuranceIframe();
    // Don't grant access here. Wait for your server to confirm the result.
  }
});

Step 5: Get the result on your server

The redirect and the DOM message aren't the result. 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_AGE_GATE_AGE_ASSURANCE",
    "status": "PASS",
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
  }
}
statusWhat you do
PASSk-ID created the session. Store sessionId and continue to Step 6.
FAILThe user didn't prove their age. No session was created; don't let them in.
IN_PROGRESSKeep waiting.
// Express webhook handler (verify the webhook signature first; see /webhooks)
app.post("/webhooks/k-id", async (req, res) => {
  const { eventType, data } = req.body;
  if (eventType === "Challenge.StateChange" && data.type === "CHALLENGE_AGE_GATE_AGE_ASSURANCE") {
    if (data.status === "PASS") {
      await savePlayerSession(data.id, data.sessionId);
    } else if (data.status === "FAIL") {
      await markAgeCheckFailed(data.id);
    }
  }
  res.sendStatus(200);
});

k-ID doesn't send a Session.Created webhook for a session created after this check. The sessionId on Challenge.StateChange is how you learn about it.

Step 6: Load the session and let the user in

Call GET /session/get with the sessionId, and turn features on from each permission's enabled value.

GET /api/v1/session/get?sessionId=608616da-4fd2-4742-82bf-ec1d4ffd8187

The session includes ageVerification, the result of the check. Features that need a verified age at or below the age the user proved are already enabled, so a later feature-level check for them is granted without asking again.

Step 7: Test it

In test mode, call /age-gate/check with an age at or above your trigger age and complete the check from the challenge URL. Test mode challenge URLs expire after 7 minutes. Confirm that:

  • the response is a CHALLENGE_AGE_GATE_AGE_ASSURANCE challenge with no session
  • your webhook receives Challenge.StateChange with status: PASS and a sessionId
  • /session/get returns the session with ageVerification

Then call /age-gate/check with an age below the trigger age and confirm the user isn't asked to verify.

What's next?

On this page