{"_id":"56ace4611c09150d00a18379","githubsync":"","version":{"_id":"56acd71213ac890d001c3c7d","project":"56acd71213ac890d001c3c7a","__v":15,"createdAt":"2016-01-30T15:30:26.928Z","releaseDate":"2016-01-30T15:30:26.928Z","categories":["56acd71313ac890d001c3c7e","56acd8f113ac890d001c3c81","56acd8f95ac4060d0027865e","56acd93a13ac890d001c3c82","56ad20660ab3c00d00ce3347","56ad356a2a7860170013f714","56ad47eb0ab3c00d00ce334f","56afd523bc304a0d00ace1df","56b29a019621f20d00efb37e","56b657e11bc6970d009feee7","5845cc3c39950c1b002afe77","5845cde163c11b250037967e","5846efd45d064323007b17b4","588604da4674e32300efd160","588627882393d50f00f1322c"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":23,"category":{"_id":"56acd93a13ac890d001c3c82","__v":4,"pages":["56acdb1c13ac890d001c3c83","56ace30c5ac4060d00278664","56ace4611c09150d00a18379","56acebfb13ac890d001c3c8a"],"project":"56acd71213ac890d001c3c7a","version":"56acd71213ac890d001c3c7d","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-30T15:39:38.798Z","from_sync":false,"order":1,"slug":"authorization","title":"Authorization"},"project":"56acd71213ac890d001c3c7a","parentDoc":null,"user":"56acd6caa040860d00ac94a2","updates":["56c2394633a0870d00feb352","56c39bd8c4796b0d007ef016"],"next":{"pages":[],"description":""},"createdAt":"2016-01-30T16:27:13.350Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Did you Register an Application?\",\n  \"body\": \"Don't forget that you need to have an application registered to complete the next steps. Check out the [Registering an Application](https://gamewisp.readme.io/docs/api-authorization) section to see how.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Quick Start\"\n}\n[/block]\nTo connecting to a GameWisp channel, your application will need to perform these five basic steps:\n\n1. Build a url to the authorize endpoint and put it in a link on a page on your site.\n2. Once the user clicks on that link, they’ll be directed to the [/oauth/authorize](https://gamewisp.readme.io/docs/oauthauthorize) endpoint on GameWisp.\n3. The user will either approve access to your app or decline. In either case, they’ll be redirected to the ** redirect_uri** you specify with an authorization code (in the case of approval) or an error (in the case of denying access).\n5. If the user approved access, take the code parameter and use the [/oauth/token](https://gamewisp.readme.io/docs/oauthtoken) endpoint to receive an **access_ token** and a** refresh_token**.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Keep your Refresh Tokens up to Date!\",\n  \"body\": \"A refresh token expires in 70 days, be sure that you're properly refreshing your access tokens before a refresh token's expiry or you will be forced to re-authenticate users. This is required even if you're only using Singularity.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Walkthrough\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Use a Comma to Split Multiple Scopes\",\n  \"body\": \"If you require [more than one scope](https://gamewisp.readme.io/docs/scopes), remember to use a comma as the scope delimiter. See the example code below.\"\n}\n[/block]\nBuild a URL to the authorize endpoint located at /api/v1/oauth/authorize and put it somewhere that a user can click on it.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n$query = http_build_query([\\n  'response_type' => 'code',\\n  'client_id' => 'YOUR_CLIENT_ID',\\n  'clientSecret' => 'YOUR_APPLICATIONS_SECRET',\\n  'redirect_uri' => 'YOUR_CLIENT_REDIRECT_URI',\\n  'scope' => 'read_only',\\n  'state' => 'base64 encoded state string -- required, can be meaningless'\\n]);\\n\\nheader(\\\"Location: https://api.gamewisp.com/pub/v1/oauth/authorize?$query\\\");\\nexit;\",\n      \"language\": \"php\",\n      \"name\": null\n    },\n    {\n      \"code\": \"//The following example uses NodeJS with Express and the simple-oauth2 packages.\\n\\nvar app = require('express')();\\n\\nvar oAuthInfo = {\\n  site: 'https://api.gamewisp.com',\\n  clientID: 'your client ID',\\n  clientSecret: 'your client secret',\\n  tokenPath: '/pub/v1/oauth/token',\\n  authorizationPath: '/pub/v1/oauth/authorize',\\n};  \\n\\nvar oauth2 = require('simple-oauth2')(oAuthInfo);\\n\\n// Authorization uri definition \\nvar authorization_uri = oauth2.authCode.authorizeURL({\\n  redirect_uri: 'your-redirect-uri',\\n  scope: 'read_only',\\n  state: 'base64 encoded state data, passed back to you'\\n});\\n\\n//redirects to the gamewisp authorize page.\\napp.get('/auth', function(req, res){\\n  res.redirect(authorization_uri);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": null\n    },\n    {\n      \"code\": \"https://api.gamewisp.com/pub/v1/oauth/authorize?client_id=CLIENT_ID_HERE&redirect_uri=REDIRECT_URI_HERE&response_type=code&scope=read_only&state=ASKDLFJsisisks23k\",\n      \"language\": \"text\"\n    },\n    {\n      \"code\": \"$code = $_GET['code'];\\n$post = [\\n         'grant_type'     => 'authorization_code',\\n         'client_id'      => 'YOUR_CLIENT_ID',\\n         'client_secret'   => 'YOUR_CLIENT_SECRET',\\n         'redirect_uri'   => 'YOUR_REDIRECTION_HERE',\\n         'code'           => $code,\\n  \\t\\t\\t 'state'\\t\\t\\t\\t\\t=> 'AXJDJSS'\\n       ];\\n\\n$ch = curl_init('https://api.gamewisp.com/pub/v1/oauth/token');\\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\\ncurl_setopt($ch, CURLOPT_POST, 1);\\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $post);\\n$response = curl_exec($ch);\\ncurl_close($ch);\\n$result = json_decode($response);\\n\\n/** Now that we've parsed the returned data, here are your tokens **/\\n$access_token  =  $result->data->access_token;\\n$refresh_token = $result->data->refresh_token;\\n\",\n      \"language\": \"php\",\n      \"name\": \"PHP-cURL\"\n    }\n  ]\n}\n[/block]\nOnce the user clicks the URL, they'll be taken to a page that looks like the following:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/XvqBOb2pQTGlUvx2IxqE_auth_page.png\",\n        \"auth_page.png\",\n        \"816\",\n        \"581\",\n        \"#b63c3a\",\n        \"\"\n      ],\n      \"border\": true,\n      \"caption\": \"The authorization page displayed for the user after clicking an authorization url.\"\n    }\n  ]\n}\n[/block]\nRegardless of whether or not the user clicks \"Accept\" or \"Deny\" they will be redirected back to the Redirect URL you supplied when you initially registered your application with GameWisp.\n\nIf the user clicks \"Deny\" they will be redirected and an error message will be passed to your Redirect URL. If the user clicks \"Accept\" they will be redirect and an authorization code and your state parameter will be passed back to your Redirect URL.\n\nOnce you receive the authorization code, send it to the [/oauth/token](https://gamewisp.readme.io/docs/oauthtoken) endpoint to exchange the code for a token.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" // assume $code is obtained via redirect from the user visiting a url of the following structure:\\n // https://gamewisp.com/pub/v1/oauth/authorize?client_id=CLIENT_ID_HERE&redirect_uri=REDIRECT_URI_HERE&response_type=code&scope=read_only\\n\\n //if using Guzzle 6+ change \\\"body\\\" to \\\"form_params\\\"\\n\\n$response = $guzzleClient->post('https://gamewisp.com/pub/v1/oauth/token', [\\n       'form_params' => [\\n         'grant_type'    => 'authorization_code',\\n         'client_id'     => 'your client ID',\\n         'client_secret' => 'your client secret',\\n         'redirect_uri'  => 'your redirect uri',\\n         'code'          => $code,\\n\\t\\t\\t\\t 'state'\\t\\t\\t\\t => 'ADFASAWW'\\n       ]\\n     ]);\\n\\n$result = json_decode($response->getBody());\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"//The following example uses NodeJS with Express and the simple-oauth2 packages.\\n\\nvar app = require('express')();\\nvar oauth2 = require('simple-oauth2')(oAuthInfo);\\n\\napp.get('your-redirect-uri', function(req, res){\\n\\tvar token = oauth2.authCode.getToken({\\n    code: code,\\n    redirect_uri: 'your-redirect-uri'\\n  }).then(function saveToken(result){\\n    token = oauth2.accessToken.create(result);\\n    accessToken = token.token.data.access_token;\\n    //store and use the token...\\n\\n  }).catch( function logError(error){\\n    //your error catching here.\\n});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \" //token structure is as follows:\\ntoken:\\n    { \\n      result: { status: 1, message: 'Token issued' },\\n      data:\\n      { \\n        access_token: 'the-access-token',\\n        token_type: 'Bearer',\\n        expires_in: 3600,\\n        refresh_token: 'the-refresh-token' \\n      },\\n      expires_at: token-expiry-time (UTC) \\n    }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAfter exchanging a code for a token, then token JSON object will contain an **access_token** and a **refresh_token**. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Working with Refresh Tokens\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Refresh Tokens Expire\",\n  \"body\": \"Refresh tokens expire after 70 days. Be sure to update the refresh token before the 70 day period or you will have to re-authenticate users manually.\"\n}\n[/block]\nYou will need to use the **refresh_token** to update the **access_token** when it expires. Access tokens are updated by passing the **refresh_token** to the [/oauth/token](https://gamewisp.readme.io/docs/oauthtoken) endpoint.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// if using Guzzle 6+ change \\\"body\\\" to \\\"form_params\\\"\\n$response = $guzzleClient->post('https://gamewisp.com/pub/v1/oauth/token', [\\n    'body' => [\\n      'grant_type'    => 'refresh_token',\\n      'client_id'     => 'your client ID',\\n      'client_secret' => 'your client secret',\\n      'redirect_uri'  => 'your redirect uri',\\n      'refresh_token' => 'the refresh token'\\n    ]\\n  ]);\\n\\n  $result = $response->json();\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"//The following example uses NodeJS with the simple-oauth2 packages.\\n\\nvar oAuthInfo = {\\n  site: 'https://gamewisp.com',\\n  clientID: 'your client ID',\\n  clientSecret: 'your client secret',\\n  tokenPath: '/pub/v1/oauth/token',\\n  authorizationPath: '/pub/v1/oauth/authorize',\\n};\\n\\nvar oauth2 = require('simple-oauth2')(oAuthInfo);\\n\\n// Sample of a JSON access token you obtained through previous steps\\nvar token = {\\n  'access_token': 'access_token',\\n  'refresh_token': 'refresh_token',\\n  'expires_in': '3600'\\n};\\n\\nvar token = oauth2.accessToken.create(token);\\n\\nif (token.expired()) {\\n  token.refresh(function(error, result) {\\n    token = result;\\n  });\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nUpon proper exchange of the refresh token, you will receive a response of the following format\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"result\\\": {\\n    \\\"status\\\": 1,\\n    \\\"message\\\": \\\"Token issued\\\"\\n  },\\n  \\\"data\\\": {\\n    \\\"access_token\\\": \\\"new-access-token\\\",\\n    \\\"token_type\\\": \\\"Bearer\\\",\\n    \\\"expires_in\\\": 3600,\\n    \\\"refresh_token\\\": \\\"new-refresh-token\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Store the new Refresh Token!\",\n  \"body\": \"New refresh tokens are randomly generated when exchanging your current refresh token for a new access token. Be sure to store the new refresh_token too.\"\n}\n[/block]\nBe sure to update your access_tokens before your refresh tokens expire. The best way to do this is likely with some sort of nightly job that updates the access_tokens of connected users. \n\nIf a refresh_token expires before you use it, you will be forced to manually reauthenticate the connected user, typically by requiring the user to come back to your application and authorize it again.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What Next?\"\n}\n[/block]\nThat's it! You've successfully authorized your client access to a GameWisp channel's data. Now check out the** RESTful API **and **Singularity** sections of this documentation to see what you can do.","excerpt":"This page details how to connect your application to a GameWisp channel.","slug":"connecting-to-a-gamewisp-channel","type":"basic","title":"Connecting to a GameWisp Channel"}

Connecting to a GameWisp Channel

This page details how to connect your application to a GameWisp channel.

[block:callout] { "type": "info", "title": "Did you Register an Application?", "body": "Don't forget that you need to have an application registered to complete the next steps. Check out the [Registering an Application](https://gamewisp.readme.io/docs/api-authorization) section to see how." } [/block] [block:api-header] { "type": "basic", "title": "Quick Start" } [/block] To connecting to a GameWisp channel, your application will need to perform these five basic steps: 1. Build a url to the authorize endpoint and put it in a link on a page on your site. 2. Once the user clicks on that link, they’ll be directed to the [/oauth/authorize](https://gamewisp.readme.io/docs/oauthauthorize) endpoint on GameWisp. 3. The user will either approve access to your app or decline. In either case, they’ll be redirected to the ** redirect_uri** you specify with an authorization code (in the case of approval) or an error (in the case of denying access). 5. If the user approved access, take the code parameter and use the [/oauth/token](https://gamewisp.readme.io/docs/oauthtoken) endpoint to receive an **access_ token** and a** refresh_token**. [block:callout] { "type": "warning", "title": "Keep your Refresh Tokens up to Date!", "body": "A refresh token expires in 70 days, be sure that you're properly refreshing your access tokens before a refresh token's expiry or you will be forced to re-authenticate users. This is required even if you're only using Singularity." } [/block] [block:api-header] { "type": "basic", "title": "Walkthrough" } [/block] [block:callout] { "type": "info", "title": "Use a Comma to Split Multiple Scopes", "body": "If you require [more than one scope](https://gamewisp.readme.io/docs/scopes), remember to use a comma as the scope delimiter. See the example code below." } [/block] Build a URL to the authorize endpoint located at /api/v1/oauth/authorize and put it somewhere that a user can click on it. [block:code] { "codes": [ { "code": "<?php\n\n$query = http_build_query([\n 'response_type' => 'code',\n 'client_id' => 'YOUR_CLIENT_ID',\n 'clientSecret' => 'YOUR_APPLICATIONS_SECRET',\n 'redirect_uri' => 'YOUR_CLIENT_REDIRECT_URI',\n 'scope' => 'read_only',\n 'state' => 'base64 encoded state string -- required, can be meaningless'\n]);\n\nheader(\"Location: https://api.gamewisp.com/pub/v1/oauth/authorize?$query\");\nexit;", "language": "php", "name": null }, { "code": "//The following example uses NodeJS with Express and the simple-oauth2 packages.\n\nvar app = require('express')();\n\nvar oAuthInfo = {\n site: 'https://api.gamewisp.com',\n clientID: 'your client ID',\n clientSecret: 'your client secret',\n tokenPath: '/pub/v1/oauth/token',\n authorizationPath: '/pub/v1/oauth/authorize',\n}; \n\nvar oauth2 = require('simple-oauth2')(oAuthInfo);\n\n// Authorization uri definition \nvar authorization_uri = oauth2.authCode.authorizeURL({\n redirect_uri: 'your-redirect-uri',\n scope: 'read_only',\n state: 'base64 encoded state data, passed back to you'\n});\n\n//redirects to the gamewisp authorize page.\napp.get('/auth', function(req, res){\n res.redirect(authorization_uri);\n});", "language": "javascript", "name": null }, { "code": "https://api.gamewisp.com/pub/v1/oauth/authorize?client_id=CLIENT_ID_HERE&redirect_uri=REDIRECT_URI_HERE&response_type=code&scope=read_only&state=ASKDLFJsisisks23k", "language": "text" }, { "code": "$code = $_GET['code'];\n$post = [\n 'grant_type' => 'authorization_code',\n 'client_id' => 'YOUR_CLIENT_ID',\n 'client_secret' => 'YOUR_CLIENT_SECRET',\n 'redirect_uri' => 'YOUR_REDIRECTION_HERE',\n 'code' => $code,\n \t\t\t 'state'\t\t\t\t\t=> 'AXJDJSS'\n ];\n\n$ch = curl_init('https://api.gamewisp.com/pub/v1/oauth/token');\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_POST, 1);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $post);\n$response = curl_exec($ch);\ncurl_close($ch);\n$result = json_decode($response);\n\n/** Now that we've parsed the returned data, here are your tokens **/\n$access_token = $result->data->access_token;\n$refresh_token = $result->data->refresh_token;\n", "language": "php", "name": "PHP-cURL" } ] } [/block] Once the user clicks the URL, they'll be taken to a page that looks like the following: [block:image] { "images": [ { "image": [ "https://files.readme.io/XvqBOb2pQTGlUvx2IxqE_auth_page.png", "auth_page.png", "816", "581", "#b63c3a", "" ], "border": true, "caption": "The authorization page displayed for the user after clicking an authorization url." } ] } [/block] Regardless of whether or not the user clicks "Accept" or "Deny" they will be redirected back to the Redirect URL you supplied when you initially registered your application with GameWisp. If the user clicks "Deny" they will be redirected and an error message will be passed to your Redirect URL. If the user clicks "Accept" they will be redirect and an authorization code and your state parameter will be passed back to your Redirect URL. Once you receive the authorization code, send it to the [/oauth/token](https://gamewisp.readme.io/docs/oauthtoken) endpoint to exchange the code for a token. [block:code] { "codes": [ { "code": " // assume $code is obtained via redirect from the user visiting a url of the following structure:\n // https://gamewisp.com/pub/v1/oauth/authorize?client_id=CLIENT_ID_HERE&redirect_uri=REDIRECT_URI_HERE&response_type=code&scope=read_only\n\n //if using Guzzle 6+ change \"body\" to \"form_params\"\n\n$response = $guzzleClient->post('https://gamewisp.com/pub/v1/oauth/token', [\n 'form_params' => [\n 'grant_type' => 'authorization_code',\n 'client_id' => 'your client ID',\n 'client_secret' => 'your client secret',\n 'redirect_uri' => 'your redirect uri',\n 'code' => $code,\n\t\t\t\t 'state'\t\t\t\t => 'ADFASAWW'\n ]\n ]);\n\n$result = json_decode($response->getBody());", "language": "php" }, { "code": "//The following example uses NodeJS with Express and the simple-oauth2 packages.\n\nvar app = require('express')();\nvar oauth2 = require('simple-oauth2')(oAuthInfo);\n\napp.get('your-redirect-uri', function(req, res){\n\tvar token = oauth2.authCode.getToken({\n code: code,\n redirect_uri: 'your-redirect-uri'\n }).then(function saveToken(result){\n token = oauth2.accessToken.create(result);\n accessToken = token.token.data.access_token;\n //store and use the token...\n\n }).catch( function logError(error){\n //your error catching here.\n});", "language": "javascript" }, { "code": " //token structure is as follows:\ntoken:\n { \n result: { status: 1, message: 'Token issued' },\n data:\n { \n access_token: 'the-access-token',\n token_type: 'Bearer',\n expires_in: 3600,\n refresh_token: 'the-refresh-token' \n },\n expires_at: token-expiry-time (UTC) \n }", "language": "json" } ] } [/block] After exchanging a code for a token, then token JSON object will contain an **access_token** and a **refresh_token**. [block:api-header] { "type": "basic", "title": "Working with Refresh Tokens" } [/block] [block:callout] { "type": "warning", "title": "Refresh Tokens Expire", "body": "Refresh tokens expire after 70 days. Be sure to update the refresh token before the 70 day period or you will have to re-authenticate users manually." } [/block] You will need to use the **refresh_token** to update the **access_token** when it expires. Access tokens are updated by passing the **refresh_token** to the [/oauth/token](https://gamewisp.readme.io/docs/oauthtoken) endpoint. [block:code] { "codes": [ { "code": "// if using Guzzle 6+ change \"body\" to \"form_params\"\n$response = $guzzleClient->post('https://gamewisp.com/pub/v1/oauth/token', [\n 'body' => [\n 'grant_type' => 'refresh_token',\n 'client_id' => 'your client ID',\n 'client_secret' => 'your client secret',\n 'redirect_uri' => 'your redirect uri',\n 'refresh_token' => 'the refresh token'\n ]\n ]);\n\n $result = $response->json();", "language": "php" }, { "code": "//The following example uses NodeJS with the simple-oauth2 packages.\n\nvar oAuthInfo = {\n site: 'https://gamewisp.com',\n clientID: 'your client ID',\n clientSecret: 'your client secret',\n tokenPath: '/pub/v1/oauth/token',\n authorizationPath: '/pub/v1/oauth/authorize',\n};\n\nvar oauth2 = require('simple-oauth2')(oAuthInfo);\n\n// Sample of a JSON access token you obtained through previous steps\nvar token = {\n 'access_token': 'access_token',\n 'refresh_token': 'refresh_token',\n 'expires_in': '3600'\n};\n\nvar token = oauth2.accessToken.create(token);\n\nif (token.expired()) {\n token.refresh(function(error, result) {\n token = result;\n });\n}", "language": "javascript" } ] } [/block] Upon proper exchange of the refresh token, you will receive a response of the following format [block:code] { "codes": [ { "code": "{\n \"result\": {\n \"status\": 1,\n \"message\": \"Token issued\"\n },\n \"data\": {\n \"access_token\": \"new-access-token\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"refresh_token\": \"new-refresh-token\"\n }\n}", "language": "json" } ] } [/block] [block:callout] { "type": "warning", "title": "Store the new Refresh Token!", "body": "New refresh tokens are randomly generated when exchanging your current refresh token for a new access token. Be sure to store the new refresh_token too." } [/block] Be sure to update your access_tokens before your refresh tokens expire. The best way to do this is likely with some sort of nightly job that updates the access_tokens of connected users. If a refresh_token expires before you use it, you will be forced to manually reauthenticate the connected user, typically by requiring the user to come back to your application and authorize it again. [block:api-header] { "type": "basic", "title": "What Next?" } [/block] That's it! You've successfully authorized your client access to a GameWisp channel's data. Now check out the** RESTful API **and **Singularity** sections of this documentation to see what you can do.