Authentication Web Service

The Authentication API allows Kongregate players to play any game without registering or entering a password. By making a call to the web service from your game server you can securely determine the player's Kongregate user id and username.

Note: This method should only be called from a server as to not expose your API key.

When the user plays your game for the first time, you will typically need to create an account in your user database for them. In most cases you can simply do this silently (as most Facebook games do) - simply create a user in your database with a column for the Kongregate user id and username. The username should be the same as the Kongregate name, if available. On future visits you'll use the Kongregate user id to retrieve the account in your database and log them in.

If a player is not logged into Kongregate, you'll want to display a friendly message saying something like "This multiplayer game requires a Kongregate account" with a "Sign in or register" button that displays our registration lightbox.

If you have a large existing user database you may need to allow players to link their Kongregate accounts to an existing account in your database. Since most users will not need to do this, you should generally just have a small link that says "Use your existing AwesomeGame.com account" and not show a username and password field until they click that - otherwise you may confuse users and lower your conversion rate. Once the player has linked their accounts, you should log them in automatically on future visits.

For more best practices on handling Kongregate guest users, see this document.

A flowchart showing the recommended flow for using the Kongregate APIs when loading your game can be found by clicking here.

Authentication Tokens

Authentication is done with a unique key for each game to prevent potential malicious game authors from stealing credentials and using them on other games. The key is called the game_auth_token, and is provided by the client API - details are here.

Request Format

Example: Successful authentication

{
  "success": true,
  "username": "BenV",
  "user_id": 765
}

Example: Failed authentication due to invalid credentials

This error occurs when any of the 3 required parameters is incorrect. This may indicate that the user needs to reload their game if they have changed their password.

{
  "success": false,
  "error": 403,
  "error_description": "Invalid credentials"
}

Example: Bad request due to missing required params

This error occurs when any of the 3 required parameters is missing.

{
  "success": false,
  "error": 400,
  "error_description": "user_id, game_auth_token, and api_key are required parameters"
}