Kongregate Web Services API

The Kongregate Web Services API is designed to allow you to integrate your existing game server with the Kongregate back end. This integration allows the user to log into your game automatically while playing on Kongregate, removing the need to create a separate account. This leads to a more seamless experience, which typically leads to many more gameplays and a higher rating.

Note that for now, all web services are designed only for server-to-server purposes, as using them from the client would expose your api_key. We hope to make some of these services available to the client in the near future.

Kongregate Client API

In order to use the web services API, it is required that you implement the Kongregate Client API which will allow you to retrieve information about the player such as their user id and game authentication token.

Game API Keys

All web requests require an API key. You can find information on retrieving your key here

Game Authentication Tokens

Authentication tokens are used for validating that a Kongregate user is who they claim to be. These tokens are unique per-user and per-game. Certain actions such as authentication and using items require this token in order to complete successfully. Note that tokens will change occasionally, for example when the user changes their password, so you cannot assume that it will be constant for a user.

Client Integration

The user's game_auth_token and user_id can be retrieved with the getGameAuthToken() and getUserId() functions on the Kongregate services API object, for example: 

kongregate.services.getUserId();
kongregate.services.getGameAuthToken();

Your game client can then pass the user_id and game_auth_token to the game server. This is typically done at login time by sending them as the username and password, but you can implement this in any way you want.

Ideally, your server application should hold on to this token while the user is connected so that it can be retrieved from memory whenever it is needed. You will need to re-authenticate the token each time the user logs in.

HTTP responses

The HTTP status codes will be 200 as long as there is not an internal server error or a scheduled downtime. All requests return JSON strings - there's sure to be a JSON parsing library for your programming language. Every request has a success field which will be true or false, along with error and error_description fields if an error occurs.

HTTP Callbacks

You can specify an API callback URL to receive notifications when certain events happen on Kongregate. The documentation for API callbacks can be found here

Getting Started With Authentication/Kreds

To get started, please read this document about the steps required for integrating authentication and microtransactions.

Services