Web Services Authentication API

User Experience

The intent of this API is to allow Kongregate players to play any multiplayer game without registering or entering a password. By making a call to the web service you can securely determine the player's Kongregate user id and username. 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 db 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 brings up our registration lightbox by calling:

kongregate.services.showSignInBox();

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.

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.

Authentication Web Service

This HTTP endpoint allows you to authenticate a user.

GET url: http://www.kongregate.com/api/authenticate.json
required params:
  user_id: The Kongregate user id for the user
  game_auth_token: The game_auth_token for the game/user combination
  api_key: The api key assigned to your game

response fields:
  success: true/false depending on if the request was successful
  user_id: The user id of the user
  username: The username of the user
  error: error code integer, if any
  error_description: error code description string, if any

Example: Successful authentication

GET http://www.kongregate.com/api/authenticate.json?user_id=765&game_auth_token=AuthToken&api_key=MyApiKey
{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.

GET http://www.kongregate.com/api/authenticate.json?user_id=765&game_auth_token=BadToken&api_key=MyApiKey
{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.

GET http://www.kongregate.com/api/authenticate.json?user_id=756
{success:false, error:400, error_description:"user_id, game_auth_token, and api_key are required parameters"}