Server Side Authorization Flow

User authentication and application authorization are handled as a two step process by redirecting the user to the login screen, followed by the authorization screen.

Authentication & Authorization

To enter the authentication/authorization flow, you must pass the following parameters to the authorization URL:

Oauth URL

https://www.geni.com/platform/oauth/authorize

Parameters

Name Description Required
client_id Application key generated during the app registration. true
redirect_uri URL that the user's browser will be redirected back to once the application authorization is completed. You can specify this URL in your application settings as a Callback URL, or pass it as a request paremeter. The redirect_uri must be within the same domain as the Site Domain you specified in the application settings. true
response_type For the server side flow the response type is defaulted to "code" and you don't need to pass it as a parameter. false
scope A comma delimited list of permissions that the application needs. By default the scope is set to a full data access. false
display For the server side flow the display parameter is defaulted to "web". false
state Used for additional parameters and CSRF protection. false

Example

https://www.geni.com/platform/oauth/authorize?client_id=YOUR_APP_KEY&redirect_uri=YOUR_URL

If the user is already logged in, we validate the login cookie that we have stored on the user's browser and authenticate the user. If the user is not logged in, they are prompted to enter their credentials:

Once we have successfully authenticated the user, we will prompt the user to authorize your application:

If the user presses Don't Allow, your app is not authorized. The user will be redirected (via HTTP 302) to the URL you passed in the redirect_uri parameter with the following error information:

Returned Fields

Name Type Description
status String If user cancels tde autdorization flow, tde status will be set to "unauthorized".
message String Error message

Example

http://YOUR_URL?status=unauthorized&message=user+canceled

If the user presses Allow, your app is authorized. The user will be redirected (via HTTP 302) to the URL you passed in the redirect_uri parameter with an authorization code:

Returned Fields

Name Type Description
code String Authorization code
expires_in Number Seconds until the code is expired
scope String List of permissions that the user has agreed to accept.
state String Will return whatever was passed to the Oauth URL.

Example

http://YOUR_URL?code=A_CODE_GENERATED_BY_SERVER&expires_in=SECONDS_UNTIL_THE_CODE_IS_EXPIRED

With this code in hand, you can proceed to the next step, app authentication, to gain the access token you need to make API calls.

Application Authorization

In order to authenticate your app, you must pass the following parameter to the request_token endpoint:

Oauth Endpoint

https://www.geni.com/platform/oauth/request_token

Parameters

Name Description Required
client_id Application key generated during the app registration. true
client_secret Application secret generated during the registration process and availble in the application settings. true
redirect_uri URL that was used to get the authorization code.The redirect_uri must be within the same domain as the Site Domain you specify in the application settings. true
code Authorization code received in the previous step. true
grant_type For the server side flow the response type is defaulted to "authorization_code" and you don't need to set it. false

Example

https://www.geni.com/platform/oauth/request_token?client_id=YOUR_APP_ID&redirect_uri=YOUR_URL&client_secret=YOUR_APP_SECRET&code=THE_CODE_FROM_ABOVE

If your app is successfully authenticated and the authorization code from the user is valid, the authorization server will return the access token in a JSON format:

Returned Fields

Name Type Description
access_token String Access token to be used with every API request
expires_in Number Seconds until the token will expire
refresh_token String Token that can be used to get a new access token

Example

{"expires_in":86400,"refresh_token":"wEq6FMb3CcfPN6CckQv7","access_token":"sye4NMd130L4wqq13zjqqLHwuHd5jnnKwdVi9S8X"}

If your app failed to provide appropriate parameters, you will get one of the errors below in JSON format:

Returned Fields

Name Type Description
error String Error code
error_description String Error description

Examples

{"error_description":"invalid client application id","error":"unauthorized_client"}

{"error_description":"redirection url must match the url used for the code request","error":"invalid_request"}

Full Example in PHP

The following example demonstrates an authentication/autherization flow in a single PHP page.The example uses CSRF protection for extra security.

<?php 

   $app_id = "YOUR_APP_KEY";
   $app_secret = "YOUR_APP_SECRET";
   $my_url = "YOUR_URL";

   session_start();
   $access_code = $_REQUEST["code"];

   if (empty($access_code)) {
     $_SESSION['state'] = md5(uniqid(rand(), TRUE)); // CSRF protection
		 
     $geni_oauth_url = "http://www.facebook.com/dialog/oauth?client_id=" . $app_id 
		                   . "&redirect_uri=" . urlencode($my_url) . "&state=" . $_SESSION['state'];
											 
     echo("<script> top.location.href='" . $geni_oauth_url . "'</script>");
   }

   if ($_REQUEST['state'] == $_SESSION['state']) {
     $token_url = "https://www.geni.com/oauth/request_token?client_id=" . $app_id . "&client_secret=" . $app_secret
           			 . "&redirect_uri=" . urlencode($my_url) . "&code=" . $access_code;

     $params = json_decode(file_get_contents($token_url), true);

     $geni_api_url = "https://www.geni.com/api/profile?access_token=" . $params['access_token'];

     $profile = json_decode(file_get_contents($geni_api_url));
		 
     echo("Hello " . $profile->name);
   } else {
	 
     echo("Error: CSRF validation failed. Someone is attacking your site!");
   }
?>

Refreshing Access Token

If your access token has expired and you have a refresh token, you can get a new access token for the same scope by calling the oauth endpoint:

Oauth Endpoint

https://www.geni.com/platform/oauth/request_token

Parameters

Name Description Required
client_id Application key generated during the app registration. true
client_secret Application secret generated during the registration process and availble in the application settings. The app secret is available from the Developer App and should not be shared with anyone or embedded in any code that you will distribute (you should use the client-side flow for these scenarios). true
redirect_uri URL that was used to get the refresh token.The redirect_uri must be within the same domain as the Site Domain you specify in the application settings. true
refresh_token Refresh token value true
grant_type In order to refresh a token, set this param to "refresh_token" true

Example

https://www.geni.com/platform/oauth/request_token?client_id=YOUR_APP_ID&redirect_uri=YOUR_URL &client_secret=YOUR_APP_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Returned Fields

Name Type Description
access_token String Access token to be used with every request to Geni API
expires_in Number Seconds until the token will expire
refresh_token String Token that can be used to get a new access token

Example

{"expires_in":86400,"refresh_token":"wEq6FMb3CcfPN6CckQv7","access_token":"sye4NMd130L4wqq13zjqqLHwuHd5jnnKwdVi9S8X"}
app007