{"__v":20,"_id":"56af71e58be2ea0d00b48887","category":{"__v":3,"_id":"56af6d6ecc4cbd0d00ce2c88","pages":["56af6e8460a37a0d00ed87ac","56af71e58be2ea0d00b48887","56af73a08be2ea0d00b48890"],"project":"56abbf55f25f160d00e17f4e","version":"56abbf55f25f160d00e17f51","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-01T14:36:30.275Z","from_sync":false,"order":2,"slug":"concepts","title":"Kongregate APIs & Concepts"},"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-02-01T14:55:33.026Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"The [Authentication API](doc:server-api-authenticate) 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.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Important\",\n  \"body\": \"Games are not permitted to require users to create an account, submit an email address, connect through Facebook, or in any other way use an authentication system that is not Kongregate's API.\"\n}\n[/block]\nWhen a 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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"A player's username can change, while the user ID will be constant - your database should always key off the user ID.\"\n}\n[/block]\nIf 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 dialog by calling: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.services.showRegistrationBox();\",\n      \"language\": \"haxe\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.services.showRegistrationBox();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Importing Existing Users\nThe one exception to the rule at the top forbidding external log-ins is that you may enable a player with a pre-existing account to connect that account to their Kongregate game. \n\nIf you do allow this, 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\". Do 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.\n\nIf players need to select a username for the game it is quickest and easiest to default to their Kongregate username (which is up to 16 characters and allows letters, numbers, and _'s).  If you are worried about name conflicts or your usernames are more restrictive, a next best option is to auto-fill a name creation field with the player's username.  This encourages them to use that name, but if it is taken or invalid it will give your normal validation error message when they try to confirm and allow them to select a new one.\n\n## Authentication Tokens\nAuthentication 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](doc:client-api-introduction) with the [getGameAuthToken](doc:client-api-services-getgameauthtoken) function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var token:String = kongregate.services.getGameAuthToken();\",\n      \"language\": \"haxe\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"var token = kongregate.services.getGameAuthToken();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Gotcha Alert\",\n  \"body\": \"You should not assume that the authentication token will remain constant for a user, as it will change any time a user changes their password.\"\n}\n[/block]\n## Authentication Web Service\n\nYou can find information about how to authenticate users from your game server [here](doc:server-api-authenticate).\n\n## Ruby OmniAuth Support\n\n[Uken Games](http://www.uken.com/) has added support for Kongregate authentication to the OmniAuth gem. [Check it out if you're a Ruby developer.](https://rubygems.org/gems/omniauth-kongregate)","excerpt":"","slug":"concepts-authentication","type":"basic","title":"Authentication"}
The [Authentication API](doc:server-api-authenticate) 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. [block:callout] { "type": "danger", "title": "Important", "body": "Games are not permitted to require users to create an account, submit an email address, connect through Facebook, or in any other way use an authentication system that is not Kongregate's API." } [/block] When a 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. [block:callout] { "type": "info", "title": "Note", "body": "A player's username can change, while the user ID will be constant - your database should always key off the user ID." } [/block] 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 dialog by calling: [block:code] { "codes": [ { "code": "kongregate.services.showRegistrationBox();", "language": "haxe", "name": "ActionScript 3" }, { "code": "kongregate.services.showRegistrationBox();", "language": "javascript" } ] } [/block] ## Importing Existing Users The one exception to the rule at the top forbidding external log-ins is that you may enable a player with a pre-existing account to connect that account to their Kongregate game. If you do allow this, 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". Do 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. If players need to select a username for the game it is quickest and easiest to default to their Kongregate username (which is up to 16 characters and allows letters, numbers, and _'s). If you are worried about name conflicts or your usernames are more restrictive, a next best option is to auto-fill a name creation field with the player's username. This encourages them to use that name, but if it is taken or invalid it will give your normal validation error message when they try to confirm and allow them to select a new one. ## 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](doc:client-api-introduction) with the [getGameAuthToken](doc:client-api-services-getgameauthtoken) function. [block:code] { "codes": [ { "code": "var token:String = kongregate.services.getGameAuthToken();", "language": "haxe", "name": "ActionScript 3" }, { "code": "var token = kongregate.services.getGameAuthToken();", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "title": "Gotcha Alert", "body": "You should not assume that the authentication token will remain constant for a user, as it will change any time a user changes their password." } [/block] ## Authentication Web Service You can find information about how to authenticate users from your game server [here](doc:server-api-authenticate). ## Ruby OmniAuth Support [Uken Games](http://www.uken.com/) has added support for Kongregate authentication to the OmniAuth gem. [Check it out if you're a Ruby developer.](https://rubygems.org/gems/omniauth-kongregate)