Skip to main content

Architecture Considerations

Client->Server vs. Server->Server​

All k-ID API calls require an Authorization header with either a valid k-ID API token or simply the API key itself. k-ID API Tokens are useful to allow k-ID to be integrated with games from smaller studios that may not have access to a customizable game backend and need to call k-ID directly from the client. For example, the k-ID Unreal Sample uses API tokens and direct k-ID calls from the client so that it is easy for developers to run locally.

On the other hand, most deployments of k-ID will be from behind a game server controlled by the studio. This is highly recommended because it protects the API key from misuse. In this case, there is no need for an API token, and the API key can be used as the authorization header for all API calls.

Getting a k-ID Token​

The client token is created from the /auth/issue-token API. The /auth/issue-token API itself requires an Authorization header which must be the k-ID API key for the game. Reminder, do not distribute a game client containing an API key. This must be stored in a safe location on a server, and at least the call to /auth/issue-token must be made from a server to k-ID and not the client.

Getting a client token from the client in Unreal C++
void UKidWorkflow::Initialize(TFunction<void(bool)> Callback)
{
   FString payload = TEXT("{ \"clientId\": \"") + ClientId + TEXT("\"}");


   HttpRequestHelper::PostRequestWithAuth(BaseUrl + 
              TEXT("/auth/issue-token"), payload, ApiKey,
              [this, Callback](FHttpResponsePtr Response, bool bWasSuccessful)
   {
       if (bWasSuccessful && Response.IsValid())
       {
           TSharedPtr<FJsonObject> JsonResponse;
           TSharedRef<TJsonReader<>> Reader = 
                TJsonReaderFactory<>::Create(Response->GetContentAsString());
           if (FJsonSerializer::Deserialize(Reader, JsonResponse))
           {
               AuthToken = JsonResponse->GetStringField(TEXT("accessToken"));
               UE_LOG(LogTemp, Log, TEXT("AuthToken generated: %s"), *AuthToken);
           }
       }
       Callback(bWasSuccessful);
   });
}

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. 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. If there is a problem with the k-ID APIs, the refresh can be deferred until later. The cached Session can be used to manage permissions without connecting to the k-ID API while the problem is resolved.

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