Skip to main content

Sessions

The k-ID Session contains the collection of permissions and age status for the current player and location. Every player requires an active Session. The game should consult the active Session to determine whether features are allowed or disallowed in the game.

What's a session?​

A k-ID Session is a long-lived object that describes a player's permissions in a game for a given jurisdiction. Every player regardless of age gets a long-lived k-ID Session which is required to access the game. The session contains the permissions for the player in the jurisdiction in which they're playing the game.

For a kid or teen, the session can be modified by a trusted adult adding or removing permissions, or a change in age because of a birthday. Sessions are generally cached in local or cloud storage by the game. Sessions can also be associated with the identity of the player in the game if the game implements player accounts.

Session lifecycle​

A k-ID Session doesn't automatically expire. It's designed to be cached in local or cloud storage associated with the player. For kids and teens, the Session can change either if a parent adds or removes permissions by using Family Connect, or the player has a birthday and "ages up" to a new age category in the jurisdiction where the session was established.

Since the Session is designed to be cached, it should be refreshed by using the /session/get API every time the game starts to get any changes that have been made.

Session structure​

A session contains:

  • sessionId: A unique identifier for the session
  • jurisdiction: The jurisdiction where the session was created
  • dateOfBirth: The player's date of birth (if collected)
  • ageStatus: The player's age status (DIGITAL_MINOR, DIGITAL_YOUTH, or LEGAL_ADULT)
  • permissions: An array of permissions with their enabled/off status
  • kuid: The k-ID user ID (if the player has been through VPC)
  • status: The session status (ACTIVE or DELETED)
  • etag: An entity tag for cache validation

Example session:

{
  "session": {
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "etag": "6d9d24fccd428f845b355122799948dd0a52fc5d",
    "jurisdiction": "US-CA",
    "kuid": "123456",
    "permissions": [
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "ai-generated-avatars"
      },
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "text-chat-private"
      }
    ],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

Getting a session​

You can retrieve a session two ways:

The /session/get API supports conditional requests by using the etag parameter. If the session hasn't changed since the last request, the API returns HTTP 304 (Not Modified), allowing you to avoid unnecessary data transfer.

Caching sessions​

The Session should be cached in local or cloud storage, and can be associated with a player's account. k-ID Sessions only change when a parent updates a permission, or a kid or teen "ages up" to the next age category, or it's deleted by the parent or player.

While it's recommended that the game refresh the Session from the /session/get API every time the game restarts, this isn't explicitly required. Additionally, k-ID Webhooks can be used to receive Session updates instead of calling the /session/get API. If there's a problem with the k-ID APIs, the refresh can also be deferred until later. A cached Session can be used to manage permissions without connecting to the k-ID API while any problem is resolved.

Sessions and player identity​

The k-ID Session can be thought of as being strongly associated with a Player's ID. If the game uses an ID system, the Session itself can be fully stored as a JSON document with storage associated with the Player's account.

Sessions across devices​

When caching Session objects in local storage, different Sessions can exist in the local storage of multiple devices for the same player. If the player plays the game on a new device, the age gate is displayed to the player, and they must seek consent again if it was required before.

To avoid having to request consent more than once, the k-ID session can be stored in cloud storage associated with the player account and retrieved whenever the player logs in on any device. In this case, there is only one Session for the player even across devices.

Session webhooks​

In the Compliance Studio, you can register a Webhook to receive events from k-ID. This avoids the need to call /session/get to retrieve infrequent changes to k-ID Sessions except for when players age up.

The following webhook events are related to sessions:

For more information, see Webhooks.