Kongregate Developers

Introduction to the REST Server-side API

There are a variety of API calls that can be made server-side to help your game interact with Kongregate. These are more secure than client-side calls and will be used for payment verification and other sensitive tasks.

Information About API Keys

Many of the API calls that you can make will require a game API key to verify your credentials as the game owner. You can retrieve the API key by adding /api on to the end of the full URL for your game. For example:

http://www.kongregate.com/games/BenV/mygame/api

Game API Key

Each game is given a unique API key, which is required for secure web requests as well as some other special functionality. You should not share your API key with anyone, which means you should not make web service calls that require the API key from your game client.

Warning: If you are trying to implement an API call via AJAX and receive a warning about CORS or cross origin resources, that generally means you are trying to access a server API with your client, and you very likely have exposed your API key in your client code. Don't do this.

REST API Callbacks

You can specify an API callback URL for your game (on the game edit form) that can be used to have your server notified when specific events happen in the Kongregate back-end. Notifications will be sent via HTTP using the POST method, and have a content type of application/x-www-form-urlencoded.

It is good practice to have your web server handle these requests quickly, as Kongregate reserves the right to terminate connections which are taking too long to complete. Ideally, one should close the connection nearly immediately, and then do any other processing elsewhere (in a queue, different thread, etc)

Callback Setup

To specify the callback URL, use the edit game page on Kongregate, and specify your API Callback URL, then save. To access the edit game URL, either click the edit link on your game page, or add /edit onto the end of your game URL:

http://www.kongregate.com/games/YourName/YourGame/edit

Callback Format

The request sent to the HTTP endpoint will always contain the following parameters:

  • event: The name of the event that triggered the callback.
  • api_key: Your game's API key. You can use this to verify which game the request is referring to, and also as protection against spoofing. If a request does not have a valid API key, you should ignore it.
  • time: The time (on our server) at which the action was performed, ex: 2016-04-10 06:20:59 -0700

Callbacks

Inventory Invalidation: invalidate_user_inventory

This callback (invalidate_user_inventory) is fired when a user's inventory is changed. This can happen when they complete a purchase. When you receive this event, you should request an updated list of the player's item instances so you can update the information on your end.

Parameters:

  • user_id: The user_id of the player who had their inventory changed.
  • username: The username of the player who had their inventory changed.
  • game_auth_token: The game_auth_token of the player who had their inventory changed.

Comments