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
- A CDK product in Compliance Studio. See Creating a product.
- 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.StateChangeevents. See Webhooks. - 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
- In Compliance Studio, open your product and select Engine & Overrides.
- Select Edit Global Rules.
- Under Product-level access, choose Yes.
- Under Who this applies to, choose the trigger age. Civil Age is the default.
- 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:
| Response | What it means | What you do |
|---|---|---|
PASS | No check is needed for this user | Store session.sessionId and continue |
PROHIBITED | The user is below the product's minimum age | Block the user |
CHALLENGE with CHALLENGE_PARENTAL_CONSENT | The user needs parental consent | Follow Custom age gate |
CHALLENGE with CHALLENGE_AGE_GATE_AGE_ASSURANCE | The user must prove their age | Continue 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"
}
}status | What you do |
|---|---|
PASS | k-ID created the session. Store sessionId and continue to Step 6. |
FAIL | The user didn't prove their age. No session was created; don't let them in. |
IN_PROGRESS | Keep 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-ec1d4ffd8187The 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_ASSURANCEchallenge with no session - your webhook receives
Challenge.StateChangewithstatus: PASSand asessionId /session/getreturns the session withageVerification
Then call /age-gate/check with an age below the trigger age and confirm the user isn't asked to verify.
What's next?
- Age assurance at features: ask for proof at protected features on the same session
- Product-level age assurance: the full reference for this check
- How verification works: methods, facial age estimation margins, and what the session records
- Pre-launch checklist