Skip to main content

Architecture Considerations

Server->Server​

All k-ID API calls require an Authorization header containing a valid k-ID API key. It is expected that k-ID APIs are called Server-to-Server to protect the k-ID API key from being exposed externally.

Game Reliability and Caching​

k-ID APIs are highly available. But it is recommended that games implement common patterns for reliability and fault tolerance (e.g. circuit breakers) for k-ID APIs when calling Server-to-Server. Since all players need a Session, games should implement a way to ensure that new and existing players are not blocked in the unlikely event that there is a problem with the k-ID Service.

Cached 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 udpates a permission, or a kid or teen "ages up" to the next age category, or it is deleted by the parent or player. While it is recommended that the game refresh the Session from the /session/get API every time the game restarts, this is not explicitly required. Also, there are ways using k-ID Webhooks to handle getting updates of Session information instead of /session/get. If there is 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.

k-ID 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.

Session.ChangePermissions and Session.Delete Webhooks​

In the k-ID Publisher Portal, 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".

Default Sessions​

For new players, it is possible to cache default permissions for each jurisdiction in the game server so that if there is a problem with the k-ID Service, reasonable defaults can be provided for new players. The /age-gate/get-default-permissions API returns default permissions per jurisdiction. Default permissions include all settings configured for the specific game, and can act as a fallback since they are not managed by a parent. Cached default k-ID permissions can also be delivered to the game through other channels (e.g. remote config).

Facial Age Estimation Download Size​

k-ID Facial Age Estimation appears in an iframe suitable for use in a Web View or external browser window. The iframe references assets from a CDN that run locally to perform the age estimation, including supporting javascript libraries and machine-learning model weights. The assets total to about 8 megabytes in size. To reduce download size when deploying k-ID within an app, the download can be avoided by bundling the supporting libraries and model weights in the app binary itself and serving them locaally from the device.