Skip to main content

Permissions upgrade

After a player has received a session with permissions, they might want to allow additional permissions. Permissions can be disallowed for reasons such as:

  1. They're below the age threshold for the permission to be enabled by default.
  2. They're below the absolute minimum required age for the permission.
  3. The permission can only be enabled with a parent/guardian's consent, and it wasn't enabled during the consent process.

Requesting new permissions​

info

The /session/upgrade API can be used to enable additional permissions. Any requested permissions which have the managedBy field set to PLAYER are enabled immediately. If there are permissions which have managedBy set to GUARDIAN, then a challenge is created for the trusted adult to complete to consent to the permission change.

When trusted adult consent is needed to enable a permission, a challenge is included in the response. This challenge can be shared similarly to the initial age gate process, by using a QR code, OTP, or email. For more information, see Challenges.

tip

One quality-of-life difference is that it's possible to use the /challenge/send-email API without specifying an email address, and the API sends an email to the trusted adult who most recently approved a permission for the player. This enables players to request permission changes without specifying an email address themselves. If no associated email address is found, the /challenge/send-email API responds with an INVALID_EMAIL error code, and you must fall back to another method, such as providing a QR code, OTP, or asking the player to enter their trusted adult's email address.

Example request​

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

{
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
  "requestedPermissions": [
    {
      "name": "voice-chat"
    }
  ]
}

Example response with challenge​

If a permission requires guardian consent, the response includes a challenge:

{
  "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 response without challenge​

If all requested permissions can be enabled by the player, the response includes the updated session:

{
  "status": "PASS",
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "permissions": [
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "voice-chat"
      }
    ]
  }
}

Handling the upgrade flow​

  1. Check permissions: Before requesting an upgrade, check the current session to see which permissions are available and which require guardian consent
  2. Request upgrade: Call /session/upgrade with the requested permissions
  3. Handle challenge: If a challenge is returned, follow the same workflow as the initial VPC flow
  4. Update session: Once consent is granted, retrieve the updated session using /session/get