Skip to main content

Sessions & permissions

Sessions and permissions are core concepts in k-ID that determine what features and capabilities a player can access in your game.

Sessions​

A 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.

For detailed information about sessions, see Sessions.

Getting a session​

You can retrieve a session two ways:

Example request​

GET /api/v1/session/get?sessionId=608616da-4fd2-4742-82bf-ec1d4ffd8187&etag=6d9d24fccd428f845b355122799948dd0a52fc5d
Authorization: Bearer your-api-key

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.

Example response​

{
  "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"
      }
    ],
    "allowances": [],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

Permissions​

Permissions represent features or capabilities in your game that could require parental consent or have age restrictions. Each permission can be allowed or disallowed for a player based on:

  • Their age and jurisdiction
  • Parental consent (if required)
  • The permission's configuration in the Compliance Studio

For detailed information about permissions, see Permissions.

Using permissions​

The game code should use each k-ID Permission to control access to the corresponding features in the game. If the enabled field is true for a permission, this means that the feature can be enabled for the player in the game. If the enabled field is false, the feature must be turned off.

The managedBy field indicates who can allow or disallow this permission:

  • PLAYER: The player can enable/disable this permission themselves
  • GUARDIAN: Only a trusted adult can enable/disable this permission
  • PROHIBITED: This permission is never allowed for the current player in the current location

If a feature is never allowed for the current player in the current location regardless of their trusted adult's consent, the managedBy field contains the value PROHIBITED. In this case, it's appropriate for the game to just remove the prohibited feature entirely from the user experience rather than show it turned off.

Upgrading permissions​

After a player has received a session with permissions, they might want to allow additional permissions. Use the /session/upgrade API to request additional permissions.

For more information, see Permissions Upgrade.

Using the permissions upgrade widget​

When building custom VPC flows with the k-ID API, you can use the permissions upgrade widget to allow players to request additional permissions that require parental consent. The widget handles the consent workflow for permission upgrades.

For general information about permissions upgrades, including when they're needed and how they work, see Permissions Upgrade in the Core concepts section.

Generating the permissions upgrade widget URL​

Call the /widget/generate-session-upgrade-url API to create a permissions upgrade widget URL. This returns a unique URL for trusted adults to review and approve additional permissions.

Example request​

POST /api/v1/widget/generate-session-upgrade-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "challengeId": "ae6d4729-af32-42ea-8ef2-ff46c7664802",
  "email": "parent@example.com"
}

Request parameters​

PropertyDescriptionRequired?
challengeIdThe ID of the VPC challenge created by /session/upgradeYes
emailThe email address of the trusted adultYes

Example response​

{
  "url": "https://family.k-id.com/widget?token=eyJhbGciOiJFUzM4NCIs..."
}

Embedding the widget​

Use the returned URL to create an iframe in your website or app. Trusted adults can review and approve additional permissions through this interface:

<iframe 
  src="WIDGET_URL" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

Receiving upgrade results​

Permission upgrades are tracked as part of the session. When additional permissions are approved, the session is updated with the new permissions. You can check the updated permissions in the session by calling the /session/get API.

For real-time updates, you can also listen for session-related events:

JavaScript events (client-side)​

For detailed information about the event structure, see Widget.ExitReview.

If the permissions upgrade widget is embedded in an iframe, you can listen for window messages from the widget:

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // Handle widget completion events
  if (message.eventType === 'Widget.ExitReview') {
    // Permissions upgrade flow completed
    console.log('Permissions upgrade completed');
    handleUpgradeCompleted();
  }
});

Webhooks (server-side)​

For detailed information about the webhook event structure, see Session.ChangePermissions.

Configure a webhook endpoint to receive session-related events. When permissions are upgraded, session changes are reflected in Session.ChangePermissions events. For more information, see Webhooks.

Permissions upgrade and sessions​

When permissions are upgraded through the widget, the session is updated with the new permissions. The session tracks which permissions have been enabled and when they were enabled. You can retrieve the session by calling the /session/get API to check the updated permissions.

For more information about how permissions upgrades work with sessions, see Permissions Upgrade in the Core concepts section.

Session caching​

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.

Session webhooks​

Configure webhooks to receive session-related events:

For more information, see Webhooks.