Age gate

An age gate is a mechanism used to collect and verify a user's age before allowing access to age-restricted content, features, or services. The k-ID API provides endpoints for managing age gates and determining what actions are required based on the player's age and jurisdiction.

Building a custom age gate UI?

For design recommendations on age sliders, date pickers, consent flows, and accessibility, see the UX guidelines.

Getting age gate requirements

Call /age-gate/get-requirements with the player's jurisdiction to determine:

• Whether an age gate should be displayed (shouldDisplay)
• What age collection methods are approved (approvedAgeCollectionMethods)
• Age thresholds:
  • digitalConsentAge: The minimum age at which a player can provide digital consent
  • civilAge: The civil/contract age at which a player is considered a legal adult
  • minimumAge: The minimum age required to access the platform/game
• Whether age assurance is required (ageAssuranceRequired)

Example request

GET /api/v1/age-gate/get-requirements?jurisdiction=US-CA
Authorization: Bearer your-api-key

Example response

{
  "shouldDisplay": true,
  "ageAssuranceRequired": true,
  "digitalConsentAge": 13,
  "civilAge": 18,
  "minimumAge": 0,
  "approvedAgeCollectionMethods": [
    "date-of-birth",
    "age-slider",
    "platform-account"
  ]
}

Including a platform age signal

If your game has a platform-reported age signal (Apple iOS, Google Play, Xbox, Meta Horizon, or k-ID), include it as query parameters: platformName, platformAgeLow, platformAgeHigh, platformCategory, platformDeclarationType, and platformVerificationId. k-ID factors the signal into shouldDisplay and ageAssuranceRequired before you collect any input: a verified adult signal lets you skip the age gate and immediately satisfy verified-age permissions. See Platform age signals for the full list of supported platforms and field shapes.

GET /api/v1/age-gate/get-requirements?jurisdiction=US-CA&platformName=apple-ios&platformAgeLow=18&platformAgeHigh=25&platformDeclarationType=governmentIDChecked
Authorization: Bearer your-api-key

Checking age for access

After collecting the player's age, call /age-gate/check with the date of birth and jurisdiction to determine the next step:

• PROHIBITED: The player's age is below the minimum age for the game. The player should be blocked from continuing.
• CHALLENGE: The player must complete a challenge before a session can be created. Inspect challenge.type to determine which challenge was returned:
  • CHALLENGE_PARENTAL_CONSENT: the claimed age is too young for the player to proceed without parental consent. A trusted adult must approve before the player can get a session.
  • CHALLENGE_AGE_GATE_AGE_ASSURANCE: the claimed age is old enough for the player to proceed without parental consent, but the product has Automatic age assurance enabled and the player must prove the claimed age (typically with a face scan or ID document) before a session is issued.
• PASS: The player can continue into the game and a session is returned on the response.

Example request

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

{
  "jurisdiction": "US-CA",
  "dateOfBirth": "2015-04-15"
}

Example CHALLENGE response

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

Example PASS response

{
  "status": "PASS",
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "jurisdiction": "US-CA",
    "permissions": [...],
    "status": "ACTIVE"
  }
}

Including a platform age signal

You can include a platformAgeSignal object in the request body, either on its own or alongside dateOfBirth/age/kuid. A verified signal can satisfy verified-age permissions without an extra verification step and records an ageVerification on the session; an unverified signal still feeds into age-conflict detection and conservative age resolution. See Platform age signals for supported platforms and verified declaration types.

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

{
  "jurisdiction": "US-CA",
  "dateOfBirth": "2005-04-15",
  "platformAgeSignal": {
    "name": "apple-ios",
    "ageLow": 18,
    "ageHigh": 25,
    "declarationType": "governmentIDChecked"
  }
}

Automatic age assurance

Automatic age assurance is an optional product configuration that verifies players whose claimed age is high enough to skip parental consent. When enabled, k-ID intercepts what would otherwise be a PASS response and returns a CHALLENGE_AGE_GATE_AGE_ASSURANCE challenge instead. The player completes facial age estimation or ID document verification themselves (no trusted adult is involved), and k-ID creates the session after verification passes.

Enabling the feature

Enabling Automatic age assurance is a two-step process:

1. An organization-level setting (allowAutomaticAgeAssurance) must be granted by k-ID. This setting is off by default and can only be toggled by k-ID. Contact k-ID support to enable it for your organization.
2. Once the setting is on, a product administrator can turn Automatic age assurance on or off per jurisdiction from the product's engine overrides in the Compliance Studio.

When it triggers

/age-gate/check returns a CHALLENGE_AGE_GATE_AGE_ASSURANCE challenge when all of the following are true:

1. Automatic age assurance is enabled for the product in the target jurisdiction.
2. The player's claimed age is at or over the age at which the player could otherwise access the product without parental consent. This is usually the jurisdiction's digital consent age, but it can be raised by a higher minimum-age configured on the product or by essential permission thresholds.
3. No trustworthy platform age signal meeting or exceeding the digital consent age was supplied with the request. A verified platform signal (for example apple-ios with declarationType: governmentIDChecked) already provides sufficient assurance and bypasses the challenge.

For claims that would otherwise require parental consent, the existing CHALLENGE_PARENTAL_CONSENT flow is used instead; Automatic age assurance doesn't change the parental consent path.

Example CHALLENGE_AGE_GATE_AGE_ASSURANCE response

{
  "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=..."
  }
}

Unlike CHALLENGE_PARENTAL_CONSENT, the response doesn't include oneTimePassword. The url points to a self-service verification page rather than the trusted-adult consent portal: the player is the one completing verification, so the URL carries a signed token and can be embedded directly as an iframe.

Handling the challenge

1. Detect the challenge type and embed challenge.url in an iframe with allow="camera;payment;publickey-credentials-get;publickey-credentials-create".
2. Listen for the Verification.Result DOM message from the iframe for responsive UI updates (see Verification.Result).
3. Confirm the outcome server-side via the Challenge.StateChange webhook or by polling /challenge/get-status. On PASS, data.sessionId contains the newly created session.
4. Call /session/get with the sessionId to retrieve the full permissions for the player.

For a walkthrough with code samples, see Handle age-assurance challenges in the custom age gate quick start guide.

Redirecting after the challenge

When the challenge runs in a top-level browser context (not an iframe), for example a mobile webview that hands off to k-ID and then back to your app, supply a redirectUrl and k-ID navigates the player to it once verification completes. Pass it as options.playerAgeAssurance.redirectUrl on /age-gate/check. The option is only honored for CHALLENGE_AGE_GATE_AGE_ASSURANCE flows and is ignored for CHALLENGE_PARENTAL_CONSENT (which already returns through the trusted-adult flow).

The URL accepts http(s) and custom-scheme mobile deeplinks (for example myapp://age-gate/return). Unsafe schemes are rejected and no redirect occurs. After the player completes or dismisses the challenge, k-ID appends the following query parameters to your URL and navigates to it:

Parameter	Description
challengeId	The challenge that was completed
productId	The product the age gate was checked against
sessionId	The newly created session (present only on PASS)
status	PASS or FAIL

Existing query parameters on the redirect URL are preserved.

Example request:

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

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

After a successful verification the player lands on, for example:

https://mygame.com/age-gate/return?challengeId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&productId=42&sessionId=608616da-4fd2-4742-82bf-ec1d4ffd8187&status=PASS

You should still confirm the outcome server-side via the Challenge.StateChange webhook or /challenge/get-status before granting access. Treat the redirect query parameters as a UX hint, not a trusted result.

Using platform age category APIs

Some platforms provide APIs that return an age category rather than a specific age or date of birth. For example, Meta Horizon provides a GetAgeCategory API that returns the categories CH (child, ages 10-12), TN (teen, ages 13-17), or AD (adult, ages 18+).

Pass the signal directly

For most integrations you can skip the conversion step and send a platformAgeSignal directly on /age-gate/check (and as query parameters on /age-gate/get-requirements). k-ID resolves category-to-range conversion server-side, factors in declaration types for verified signals, and runs age-conflict detection in one call. See Platform age signals. The conversion endpoint below is still useful when you need the age range up front to drive your own UI.

When using a platform's age category API, you need to convert the category to an age range for the player's jurisdiction, then use that age range with k-ID's age gate system.

Example: Using Meta Horizon's GetAgeCategory API

Here's a complete example of how to integrate Meta Horizon's age category API with k-ID:

1. Get the age category from Meta Horizon

// Meta Horizon Unity SDK example
var ageCategory = PlatformService.GetAgeCategory();
// Returns: "CH" (child, ages 10-12), "TN" (teen, ages 13-17), or "AD" (adult, ages 18+)

2. Convert the category to an age range

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

{
  "jurisdiction": "US-CA",
  "platform": {
    "name": "meta-horizon",
    "category": "TN"
  }
}

Response:

{
  "ageLow": 13,
  "ageHigh": 17
}

3. Use the lowest age with the age gate check

Use the ageLow value (13 in this example) as the age parameter when calling /age-gate/check:

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

{
  "jurisdiction": "US-CA",
  "age": 13
}

This ensures that the platform's verified age category is properly converted to a specific age value that can be used with k-ID's age gate system while maintaining compliance with jurisdiction-specific requirements.

Date of birth format

For information about date of birth formats and requirements, see Age Gate in the Core concepts section.

Default permissions

If /age-gate/get-requirements responds with shouldDisplay = false, then no age gate should be shown and the player's date of birth isn't defined. In this case, the game still creates a Session by retrieving default permissions for the jurisdiction by calling /age-gate/get-default-permissions, which means that permissions don't vary based on age in this jurisdiction. Some features in a game might be prohibited for all age audiences based on jurisdiction, so the game should still consult the Session permissions to check whether a feature can be enabled.