{"__v":10,"_id":"570a50cb42cbb61700228c92","category":{"__v":5,"_id":"56abca6bf9757e0d007c6650","pages":["56abcb4a678b58170031ec27","56accf7513ac890d001c3c76","56acd12a693f0a0d0085f099","56acd43d0ab3c00d00ce332d","56acd698d21f1b0d00fd2f65"],"project":"56abbf55f25f160d00e17f4e","version":"56abbf55f25f160d00e17f51","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-29T20:24:11.577Z","from_sync":false,"order":1,"slug":"api-overview","title":"API Languages"},"parentDoc":null,"project":"56abbf55f25f160d00e17f4e","user":"56abbec30b9e0b0d00616274","version":{"__v":12,"_id":"56abbf55f25f160d00e17f51","project":"56abbf55f25f160d00e17f4e","createdAt":"2016-01-29T19:36:53.665Z","releaseDate":"2016-01-29T19:36:53.665Z","categories":["56abbf56f25f160d00e17f52","56abca6bf9757e0d007c6650","56acddfa0ab3c00d00ce3332","56af65da9d32e30d0006d30f","56af66cab34d210d003d9ad0","56af6afcd21e9c0d00b628d1","56af6d6ecc4cbd0d00ce2c88","5705b12221cfed0e00e8c580","570a5676ade45d0e00c1ad33","570d7d25d1e4b82000d9e385","570eac3c3160d10e0041df0e","575709000fd6a3200010dded"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-10T13:10:35.533Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"## Introduction to the REST Server-side API\n\nThere 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.\n\n### Information About API Keys\n\nMany 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`\n\n## Game API Key\n\nEach 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.**\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Warning\",\n  \"body\": \"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.\"\n}\n[/block]\n## REST API Callbacks\n\nYou 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`.\n\nIt 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)\n\n### Callback Setup\n\nTo 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, for example: `http://www.kongregate.com/games/YourName/YourGame/edit`\n\n### Callback Format\n\nThe request sent to the HTTP endpoint will always contain the following parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`event`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The name of the event\",\n    \"1-0\": \"`api_key`\",\n    \"1-1\": \"String\",\n    \"1-2\": \"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.\",\n    \"2-0\": \"`time`\",\n    \"2-1\": \"String\",\n    \"2-2\": \"The time (on our server) at which the action was performed, ex: `2016-04-10 06:20:59 -0700`\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n### Callbacks\n\n**Inventory Invalidation: `invalidate_user_inventory`**\n\nThe `invalidate_user_inventory` callback 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](doc:server-api-item-list) of the player's item instances so you can update the information on your end.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`user_id`\",\n    \"0-1\": \"Integer\",\n    \"0-2\": \"The user_id of the player who had their inventory changed.\",\n    \"1-0\": \"`username`\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The username of the player who had their inventory changed.\",\n    \"2-0\": \"`game_auth_token`\",\n    \"2-1\": \"String\",\n    \"2-2\": \"The game_auth_token of the player who had their inventory changed.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]","excerpt":"","slug":"server-side-http","type":"basic","title":"Server Side API"}
## 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.** [block:callout] { "type": "warning", "title": "Warning", "body": "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." } [/block] ## 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, for example: `http://www.kongregate.com/games/YourName/YourGame/edit` ### Callback Format The request sent to the HTTP endpoint will always contain the following parameters: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`event`", "0-1": "String", "0-2": "The name of the event", "1-0": "`api_key`", "1-1": "String", "1-2": "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.", "2-0": "`time`", "2-1": "String", "2-2": "The time (on our server) at which the action was performed, ex: `2016-04-10 06:20:59 -0700`" }, "cols": 3, "rows": 3 } [/block] ### Callbacks **Inventory Invalidation: `invalidate_user_inventory`** The `invalidate_user_inventory` callback 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](doc:server-api-item-list) of the player's item instances so you can update the information on your end. [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`user_id`", "0-1": "Integer", "0-2": "The user_id of the player who had their inventory changed.", "1-0": "`username`", "1-1": "String", "1-2": "The username of the player who had their inventory changed.", "2-0": "`game_auth_token`", "2-1": "String", "2-2": "The game_auth_token of the player who had their inventory changed." }, "cols": 3, "rows": 3 } [/block]