Skip to main content

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.

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+)
  1. 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
}
  1. 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.